MagicApp\AppEntityDateTime

Declaration

class AppEntityDateTime { }

Package

MagicApp

Description

Class AppEntityDateTime

This class is used to handle date and time values related to a specific entity. It takes care of converting date and time values into a formatted string while considering time zones and translation maps for the application. It also offers the ability to get various date and time properties dynamically from the entity.

Properties

1. entity

Declaration

private MagicObject $entity;

Description

The entity that this class is associated with.

2. timeZone

Declaration

private DateTimeZone $timeZone;

Description

The time zone used for converting and formatting dates and times.

3. defaultDateTimeFormat

Declaration

private string $defaultDateTimeFormat;

Description

The default format used for formatting date and time.

4. defaultDateFormat

Declaration

private string $defaultDateFormat;

Description

The default format used for formatting dates (without time).

5. translationMap

Declaration

private array $translationMap;

Description

A translation map used to replace certain substrings in the formatted date/time strings.

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $entity,
    array|null $translationMap = null,
    string $defaultDateTimeFormat = 'Y-m-d H:i:s',
    string $defaultDateFormat = 'Y-m-d'
)
{
}

Description

AppEntityDateTime constructor.

This constructor initializes the object with the necessary entity and options such as default date formats and the translation map for replacing parts of the formatted date/time. It also sets the time zone based on the entity's database settings.

Parameters

$entity

The entity this class is responsible for.

$translationMap

Optional map for translating date/time strings.

$defaultDateTimeFormat

The default format for date and time.

$defaultDateFormat

The default format for date (without time).

2. convertToString

Declaration

private function convertToString(
    mixed $dateTime,
    string|null $format = null
) : string|null
{
}

Description

Converts a DateTime object or string into a formatted string.

This method takes a DateTime object or a string and converts it into a formatted date/time string. The resulting string is also adjusted to the object's time zone if necessary. If a translation map is provided, it will replace specific substrings in the formatted string.

Parameters

$dateTime

The DateTime object or string to be converted.

$format

The format in which the date/time should be returned. If not provided, defaults are used.

Return

string|null

The formatted date/time string.

3. __call

Declaration

public function __call(
    string $method,
    array $arguments
) : string|null
{
}

Description

Magic method to dynamically get properties from the entity.

This method intercepts calls to getter methods for the entity's properties and formats the result as a date/time string based on the available formats and time zone settings. It will return the formatted date/time string for the corresponding property or null if the property is not set.

Parameters

$method

The name of the called method.

$arguments

The arguments passed to the method.

Return

string|null

The formatted date/time string or null.

4. __toString

Declaration

public function __toString() : string
{
}

Description

Convert the object to a string representation.

This method converts the object into a JSON-encoded string containing key information about the object, including the time zone, date formats, translation map, and the entity name.

Return

string

JSON-encoded string containing object information.

MagicApp\AppEntityLanguage

Declaration

class AppEntityLanguage extends MagicObject\Language\PicoEntityLanguage { }

Description

Class AppEntityLanguage

This class extends PicoEntityLanguage to manage language-specific configurations for application entities. It handles loading language data from INI files based on the current language setting and the application's configuration.

Constants

const ANNOTATION_TABLE = 'Table';
const ANNOTATION_LANGUAGE = 'Language';

Properties

1. appConfig

Declaration

private SecretObject $appConfig;

Description

App config

2. currentLanguage

Declaration

private string $currentLanguage;

Description

Current language

3. fullClassName

Declaration

private string $fullClassName;

Description

Full class name of the entity

4. baseClassName

Declaration

private string $baseClassName;

Description

Base class name of the entity

5. baseLanguageDirectory

Declaration

private string $baseLanguageDirectory;

Description

Base language directory path

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $entity,
    SecretObject $appConfig,
    string $currentLanguage
)
{
}

Description

Constructor

Initializes the AppEntityLanguage with the entity, app configuration, and the current language. It loads the corresponding language values.

Parameters

$entity

The entity whose language needs to be loaded

$appConfig

The application configuration

$currentLanguage

The current language code

2. loadEntityLanguage

Declaration

public function loadEntityLanguage(
    MagicObject $entity,
    SecretObject $appConfig,
    string $currentLanguage
) : MagicObject
{
}

Description

Load entity language from an INI file based on the entity and config.

Parameters

$entity

The entity to load language for

$appConfig

The application configuration

$currentLanguage

The current language code

Return

MagicObject

The loaded language values as a MagicObject

3. baseClassName

Declaration

private function baseClassName(
    string $className,
    string|null $prefix,
    int $parent = 0
) : string
{
}

Description

Extracts the base class name from a full class name, optionally using a prefix and accounting for parent classes.

Parameters

$className

The full class name

$prefix

An optional prefix to remove

$parent

Number of parent classes to consider

Return

string

The base class name

4. getAppConfig

Declaration

public function getAppConfig() : SecretObject
{
}

Description

Get the application configuration.

Return

SecretObject

The application configuration object

5. getCurrentLanguage

Declaration

public function getCurrentLanguage() : string
{
}

Description

Get the current language code.

Return

string

The current language code

6. loadEntityLabel

Declaration

public function loadEntityLabel(
    MagicObject $entity
) : self
{
}

Description

Load data into the object from the given entity.

Parameters

$entity

The entity to load.

Return

self

Returns the current instance for method chaining.

7. addLanguage

Declaration

public function addLanguage(
    string $code,
    object|stdClass|array $reference,
    bool $use = false
) : self
{
}

Description

Add a language to the entity.

Parameters

$code

Language code.

$reference

Reference data for the language.

$use

Flag to indicate whether to use this language immediately.

Return

self

Returns the current instance for method chaining.

8. removeLanguage

Declaration

public function removeLanguage(
    string $code
) : self
{
}

Description

Remove a language from the entity.

Parameters

$code

Language code to remove.

Return

self

Returns the current instance for method chaining.

9. selectLanguage

Declaration

public function selectLanguage(
    string $code
) : self
{
}

Description

Set the current language.

Parameters

$code

Language code to set as current.

Return

self

Returns the current instance for method chaining.

10. propertyList

Declaration

public function propertyList(
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the entity.

Parameters

$asArrayProps

Flag to determine if result should be returned as an array.

Return

array

List of properties.

11. annotationContent

Declaration

private function annotationContent(
    PicoAnnotationParser $reflexProp,
    PicoGenericObject $parameters,
    string $annotation,
    string $attribute
) : mixed|null
{
}

Description

Get the content of a specific annotation.

Parameters

$reflexProp

Property reflection object.

$parameters

Parameters associated with the property.

$annotation

Annotation name to search for.

$attribute

Attribute name to retrieve.

Return

mixed|null
12. label

Declaration

private function label(
    PicoAnnotationParser $reflexProp,
    PicoGenericObject $parameters,
    string $defaultLabel
) : string
{
}

Description

Define the label for a property.

Parameters

$reflexProp

Property reflection object.

$parameters

Parameters associated with the property.

$defaultLabel

Default label to use if no annotation is found.

Return

string

The defined label.

13. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

Name of the property to set.

$propertyValue

Value to set for the property.

Return

self

Returns the current instance for method chaining.

14. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

Name of the property to get.

Return

mixed|null

The value of the property or null if not set.

15. __get

Declaration

public function __get(
    string $name
) : mixed
{
}

Description

Magic method to get property values.

Example:

 <?php
 echo $instance->foo;

Parameters

$name

Name of the property to get.

Return

mixed

Value of the property if set, otherwise null.

16. __isset

Declaration

public function __isset(
    string $name
) : bool
{
}

Description

Check if a property is set or not.

Parameters

$name

Name of the property to check.

Return

bool

True if the property is set, false otherwise.

17. __call

Declaration

public function __call(
    string $method,
    array $args
) : mixed|null
{
}

Description

Magic method to handle undefined methods.

This method allows for the dynamic handling of method calls that are not explicitly defined in the class. Specifically, it processes calls to getter methods that start with the prefix "get".

When a method starting with "get" is invoked, this method extracts the property name from the method name and calls the get method to retrieve the corresponding value.

Supported dynamic getter methods:

  • get<PropertyName>: This will call the get method with the property name derived from the method call. For example, calling $obj->getAge() would result in a call to $this->get('age').

    If the method name does not start with "get" or does not correspond to a valid property, this method will return null.

Parameters

$method

Name of the method being called, expected to start with "get".

$args

Arguments passed to the method; typically unused in this context.

Return

mixed|null

The value of the requested property if it exists; otherwise, null.

18. getTableIdentity

Declaration

public function getTableIdentity() : PicoGenericObject
{
}

Description

Get the table identity.

Return

PicoGenericObject

The table identity object.

19. getEntityLanguage

Declaration

public function getEntityLanguage() : string
{
}

Description

Get the entity language code.

Return

string

The entity language code.

20. getEntityClassName

Declaration

public function getEntityClassName() : string
{
}

Description

Get the entity class name.

Return

string

The entity class name.

21. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the object to its string representation.

This method checks if the label language and current language are set. If they are, it returns the JSON-encoded string of the label corresponding to the current language. If not, it returns an empty JSON object.

Return

string

A JSON-encoded string of the label for the current language,

22. getDefaultLabel

Declaration

public function getDefaultLabel() : array
{
}

Description

Get the value of defaultLabel

Return

array

Get default label of the entity

MagicApp\AppFormBuilder

Declaration

class AppFormBuilder { }

Description

Class AppFormBuilder

This class provides methods for building form elements, specifically select options, by fetching data from a MagicObject entity. It handles the creation of select elements with options based on specified criteria, including attributes and selection states.

Methods

1. getInstance

Declaration

public static function getInstance() : self
{
}

Description

Get an instance of the AppFormBuilder class.

Return

self

A new instance of AppFormBuilder

2. createSelectOption

Declaration

public function createSelectOption(
    MagicObject $entity,
    PicoSpecification $specification,
    PicoSortable $sortable,
    string $primaryKey,
    mixed $valueKey,
    mixed|null $currentValue = null,
    string[]|null $additionalOutput = null
) : AppFormSelect
{
}

Description

Create select options for a form element.

This method retrieves data from the specified entity using the given specification and sorting parameters. It then builds a select option list based on the retrieved data, marking the current value as selected if applicable.

Parameters

$entity

The entity to fetch data from

$specification

The specification for the query

$sortable

The sorting parameters for the results

$primaryKey

The key used for the option values

$valueKey

The key used for the option labels

$currentValue

The currently selected value (if any)

$additionalOutput

Additional attributes to include in each option

Return

AppFormSelect

The created select option element

3. createAttributes

Declaration

private function createAttributes(
    string[]|null $additionalOutput,
    MagicObject $row
) : string[]
{
}

Description

Create attributes from additional output keys.

This method retrieves specified attributes from a given row and constructs an associative array of attributes to be used in form options.

Parameters

$additionalOutput

Array of additional attribute keys

$row

The current row from which to extract attribute values

Return

string[]

An associative array of attributes

4. selected

Declaration

public static function selected(
    mixed $param1,
    mixed $param2
) : string
{
}

Description

Return 'selected="selected"' if the two parameters are equal.

This method is a utility to generate the selected attribute for HTML options.

Parameters

$param1

The first parameter for comparison

$param2

The second parameter for comparison

Return

string

The attribute string if parameters match, empty string otherwise

5. checked

Declaration

public static function checked(
    mixed $param1,
    mixed $param2
) : string
{
}

Description

Return 'checked="checked"' if the two parameters are equal.

This method is a utility to generate the checked attribute for HTML inputs.

Parameters

$param1

The first parameter for comparison

$param2

The second parameter for comparison

Return

string

The attribute string if parameters match, empty string otherwise

6. classCompareData

Declaration

public static function classCompareData(
    bool $div
) : string
{
}

Description

Add class compare data based on a boolean flag.

This method returns a CSS class string indicating whether the data is different or not based on the given boolean parameter.

Parameters

$div

The boolean flag indicating data comparison

Return

string

The class string for comparison

MagicApp\AppFormOption

Declaration

class AppFormOption { }

Description

Class AppFormOption

Represents an option within a form element, encapsulating the necessary attributes and behaviors associated with that option, including its display text, value, selection state, and any additional data attributes.

Properties

1. textNode

Declaration

private string $textNode;

Description

Text node for the option.

2. value

Declaration

private string $value;

Description

Value associated with the option.

3. selected

Declaration

private boolean $selected;

Description

Indicates whether the option is selected.

4. format

Declaration

private string $format;

Description

Format for the text node, allowing dynamic content.

5. params

Declaration

private string[] $params;

Description

Parameters for dynamic formatting of the text node.

6. data

Declaration

private MagicObject $data;

Description

Data associated with the option, typically from a MagicObject.

7. attributes

Declaration

private string[] $attributes;

Description

Additional attributes for the option.

8. pad

Declaration

private string $pad = '';

Description

Padding to format the output, e.g., for nested options.

Methods

1. __construct

Declaration

public function __construct(
    string $textNode,
    string|null $value = null,
    boolean $selected = false,
    string[]|null $attributes = null,
    MagicObject|null $data = null
)
{
}

Description

Constructor to initialize the option with text, value, selected state, attributes, and data.

Parameters

$textNode

The display text for the option

$value

The value of the option

$selected

Indicates if the option is selected

$attributes

Additional HTML attributes for the option

$data

Associated data for dynamic value retrieval

2. createAttributes

Declaration

public function createAttributes() : string
{
}

Description

Create HTML data attributes for the option.

This method generates a string of HTML data attributes from the attributes array. It formats each key into a data- attribute (e.g., data-attribute-name="value").

Return

string

Formatted string of data attributes for HTML

3. textNodeFormat

Declaration

public function textNodeFormat(
    string $format,
    string[] $params
) : self
{
}

Description

Set a format for the text node with parameters for dynamic content.

This method allows you to set a dynamic format for the text of the option. The format string can contain placeholders that will be replaced with the provided parameters.

Parameters

$format

The format string

$params

The parameters for the format

Return

self

The current instance, allowing method chaining

4. getValues

Declaration

public function getValues() : string[]
{
}

Description

Retrieve the values of the parameters used in the format.

This method returns an array of parameter values by evaluating each one through the getValue() method, which may fetch data from the associated MagicObject.

Return

string[]

Array of parameter values

5. getValue

Declaration

public function getValue(
    string $param
) : string|null
{
}

Description

Get the value associated with a given parameter.

This method retrieves the value of a parameter, which could be a property of the associated MagicObject (if it exists) or simply the parameter name.

Parameters

$param

The parameter name

Return

string|null

The value associated with the parameter, or null if not found

6. setPad

Declaration

public function setPad(
    string $pad = ' '
) : self
{
}

Description

Set padding for the option, typically for nested structures.

This method allows you to specify padding to be applied to the option, typically useful for nested option elements.

Parameters

$pad

The padding string (default is a tab character)

Return

self

The current instance, allowing method chaining

7. __toString

Declaration

public function __toString() : string
{
}

Description

Get the HTML representation of the option as a string.

This method generates the HTML markup for the option element. It includes the value, display text, selection state, and any additional attributes.

Return

string

The HTML option element

8. toString

Declaration

public function toString() : string
{
}

Description

Alias for the __toString() method.

This method is an alias for __toString() to provide a more intuitive method name for rendering the option as a string.

Return

string

The HTML option element

9. getTextNode

Declaration

public function getTextNode() : string
{
}

Description

Get the text node for the option.

This method retrieves the text content associated with the option.

Return

string

The text node

10. setTextNode

Declaration

public function setTextNode(
    string $textNode
) : self
{
}

Description

Set the text node for the option.

This method allows setting a new text value for the option.

Parameters

$textNode

The text node to set

Return

self

The current instance, allowing method chaining

11. getData

Declaration

public function getData() : MagicObject|null
{
}

Description

Get the associated data for the option.

This method retrieves the associated MagicObject that holds additional data for dynamic value retrieval.

Return

MagicObject|null

The associated data object, or null if not set

MagicApp\AppFormSelect

Declaration

class AppFormSelect { }

Description

Class AppFormSelect

Represents a select form element that can contain multiple options. Provides methods to add options, set formatting, and generate the HTML representation of the select element.

This class helps in managing and rendering a <select> HTML element with various options. It allows you to dynamically add options, format the text of the options, and generate the HTML representation of the select element.

Properties

1. options

Declaration

private AppFormOption[] $options = array();

Description

Array of options for the select element.

Methods

1. add

Declaration

public function add(
    string $textNode,
    string|null $value = null,
    boolean $selected = false,
    string[]|null $attributes = null,
    MagicObject|null $data = null
) : self
{
}

Description

Add an option to the select element.

This method adds a new option to the select element, which consists of display text, a value, a selected status, optional HTML attributes, and associated data.

Parameters

$textNode

The display text for the option

$value

The value of the option

$selected

Indicates if the option is selected

$attributes

Additional HTML attributes for the option

$data

Associated data for the option

Return

self

The current instance, allowing method chaining

2. setTextNodeFormat

Declaration

public function setTextNodeFormat(
    callable|string $format
) : self
{
}

Description

Set the text node format for all options.

This method allows you to set a format for the display text (text node) of each option in the select element. You can provide a format string or a callable function that will be applied to the associated data for each option.

Parameters

$format

A callable function or a format string

Return

self

The current instance, allowing method chaining

3. setTextNodeFormatFromString

Declaration

public function setTextNodeFormatFromString(
    string $format
) : self
{
}

Description

Set the text node format using a format string.

This method allows you to set the format for the text of each option by using a format string. The format string can contain placeholders like %s and %d to be replaced with values from the option's data.

Parameters

$format

The format string

Return

self

The current instance, allowing method chaining

4. setIndent

Declaration

public function setIndent(
    integer $indent = 1
) : self
{
}

Description

Set indentation for the options.

This method sets the level of indentation for each option's HTML representation. The indent parameter determines how many tab characters will be used for indentation.

Parameters

$indent

The level of indentation (default is 1)

Return

self

The current instance, allowing method chaining

5. __toString

Declaration

public function __toString() : string
{
}

Description

Get the HTML representation of the select element as a string.

This method generates the complete HTML representation of the <select> element, including all of its options. The options are rendered using their respective toString() method.

Return

string

The HTML representation of the select element, including options

MagicApp\AppInclude

Declaration

class AppInclude { }

Description

Class AppInclude

Manages the inclusion of application components such as headers, footers, and error pages. It provides methods to dynamically retrieve the paths to these components based on the application's configuration.

This class is responsible for generating the file paths for common application components such as the header, footer, and error pages. It also allows dynamic configuration based on the application's settings and the current module.

Properties

1. appConfig

Declaration

private SecretObject $appConfig;

Description

Application configuration.

2. app

Declaration

private SecretObject $app;

Description

Application instance.

3. currentModule

Declaration

private PicoModule $currentModule;

Description

Current module in use.

Methods

1. __construct

Declaration

public function __construct(
    SecretObject $appConfig,
    PicoModule $currentModule
)
{
}

Description

AppInclude constructor.

Initializes the AppInclude object with the application configuration and the current module. If no application is set, a new SecretObject instance is created for the app.

Parameters

$appConfig

The application configuration object.

$currentModule

The current module being used.

2. mainAppHeader

Declaration

public function mainAppHeader(
    string $dir
) : string
{
}

Description

Get the path to the main header file.

Retrieves the file path for the main header. If a custom header path is defined in the configuration, it is used, otherwise, a default path is returned.

Parameters

$dir

Base directory for includes.

Return

string

Path to the header file.

3. mainAppFooter

Declaration

public function mainAppFooter(
    string $dir
) : string
{
}

Description

Get the path to the main footer file.

Retrieves the file path for the main footer. If a custom footer path is defined in the configuration, it is used, otherwise, a default path is returned.

Parameters

$dir

Base directory for includes.

Return

string

Path to the footer file.

4. appForbiddenPage

Declaration

public function appForbiddenPage(
    string $dir
) : string
{
}

Description

Get the path to the forbidden access page.

Retrieves the file path for the forbidden access page (403). If a custom path is defined in the configuration, it is used, otherwise, a default path is returned.

Parameters

$dir

Base directory for includes.

Return

string

Path to the forbidden page (403).

5. appNotFoundPage

Declaration

public function appNotFoundPage(
    string $dir
) : string
{
}

Description

Get the path to the not found page.

Retrieves the file path for the not found page (404). If a custom path is defined in the configuration, it is used, otherwise, a default path is returned.

Parameters

$dir

Base directory for includes.

Return

string

Path to the not found page (404).

6. getAppConfig

Declaration

public function getAppConfig() : SecretObject
{
}

Description

Get the application configuration.

Returns the current application configuration object.

Return

SecretObject

The application configuration.

7. setAppConfig

Declaration

public function setAppConfig(
    SecretObject $appConfig
) : self
{
}

Description

Set the application configuration.

Allows setting a new application configuration object.

Parameters

$appConfig

The application configuration to set.

Return

self

The current instance, allowing method chaining.

8. getCurrentModule

Declaration

public function getCurrentModule() : PicoModule
{
}

Description

Get the current module.

Returns the current module that is in use.

Return

PicoModule

The current module.

9. setCurrentModule

Declaration

public function setCurrentModule(
    PicoModule $currentModule
) : self
{
}

Description

Set the current module.

Allows setting a new module as the current one.

Parameters

$currentModule

The module to set as current.

Return

self

The current instance, allowing method chaining.

10. printException

Declaration

public function printException(
    Exception $e
) : string
{
}

Description

Print exception message.

Prints the message of an exception. This method can be used for debugging or logging purposes.

Parameters

$e

The exception to print.

Return

string

The exception message.

MagicApp\AppLanguage

Declaration

class AppLanguage extends MagicObject\Language\PicoLanguage { }

Description

Class AppLanguage

Extends PicoLanguage to manage application-specific language data. Loads language strings from an INI file based on the current language setting.

Properties

1. appConfig

Declaration

private SecretObject $appConfig;

Description

Application configuration.

2. currentLanguage

Declaration

private string $currentLanguage;

Description

Current language being used.

3. callback

Declaration

private callable $callback;

Description

Callback function for handling missing properties.

Methods

1. __construct

Declaration

public function __construct(
    SecretObject|null $appConfig = null,
    string|null $currentLanguage = null,
    callable|null $callback = null
)
{
}

Description

Constructor for AppLanguage.

Parameters

$appConfig

The application configuration object.

$currentLanguage

The current language to load.

$callback

A callback function for missing properties.

2. loadLanguageData

Declaration

private function loadLanguageData() : array
{
}

Description

Load language data from the INI file.

Return

array

The parsed language data.

3. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get the value of a specified property.

If the property does not exist, the callback (if set) is called.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The property value or null if not found.

4. loadData

Declaration

public function loadData(
    stdClass|array $data
) : self
{
}

Description

Load data into the object.

Parameters

$data

Data to be loaded into the object.

Return

self

Returns the current instance for method chaining.

5. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

Name of the property to set.

$propertyValue

Value to assign to the property.

Return

self

Returns the current instance for method chaining.

6. __set

Declaration

public function __set(
    string $name,
    mixed $value
) : void
{
}

Description

Magic method to set property values.

Example:

 <?php
 $instance->foo = 'bar';

Parameters

$name

Name of the property to set.

$value

Value to assign to the property.

Return

void
7. __get

Declaration

public function __get(
    string $name
) : mixed
{
}

Description

Magic method to get property values.

Example:

 <?php
 echo $instance->foo;

Parameters

$name

Name of the property to get.

Return

mixed

The value stored in the property.

8. __isset

Declaration

public function __isset(
    string $name
) : bool
{
}

Description

Check if a property is set.

Parameters

$name

Name of the property to check.

Return

bool

True if the property is set, false otherwise.

9. __unset

Declaration

public function __unset(
    string $name
) : void
{
}

Description

Unset a property value.

Parameters

$name

Name of the property to unset.

Return

void
10. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when an undefined method is invoked.

This method provides dynamic handling for method calls that are not explicitly defined in the class. It specifically supports two types of method calls:

  1. Getter Methods:

    • When a method name starts with "get", it retrieves the corresponding property value.
    • For example, calling $obj->getAge() will invoke this method and call $this->get('age').
  2. Equality Check Methods:

    • When a method name starts with "equals", it checks if the provided parameter is equal to the corresponding property value.
    • For example, calling $obj->equalsAge($someValue) will check if $someValue is equal to the value of the age property.

    If the method does not start with "get" or "equals", this method will return null.

Parameters

$method

Name of the method being called. It should start with "get" or "equals".

$params

Parameters passed to the method; for equality checks, it typically contains the value to compare.

Return

mixed|null

The return value of the getter method or the result of the equality check (true or false), or null if the method is not recognized.

MagicApp\AppMenuGroupItem

Declaration

class AppMenuGroupItem { }

Description

Class AppMenuGroupItem

Represents a group of menu items, including a label, a CSS class, and the menu items themselves. This class is used to define a collection of related menu items, with a label and a CSS class for styling purposes.

Properties

1. label

Declaration

private string $label;

Description

Label for the menu group.

2. class

Declaration

private string $class;

Description

CSS class name associated with the menu group.

3. menuItems

Declaration

private AppMenuItem[] $menuItems = array();

Description

Array of menu items in this group.

Methods

1. getLabel

Declaration

public function getLabel() : string
{
}

Description

Get the label of the menu group.

This method returns the label associated with the menu group. The label is used to identify the menu group in the user interface.

Return

string

The label of the menu group.

2. setLabel

Declaration

public function setLabel(
    string $label
) : self
{
}

Description

Set the label for the menu group.

This method sets the label that will be associated with the menu group. The label is typically displayed in the user interface to identify the group of menu items.

Parameters

$label

The label for the menu group.

Return

self

The current instance of the class, allowing for method chaining.

3. getClass

Declaration

public function getClass() : string
{
}

Description

Get the CSS class name of the menu group.

This method returns the CSS class name associated with the menu group. The CSS class is used to style the group in the user interface.

Return

string

The CSS class name of the menu group.

4. setClass

Declaration

public function setClass(
    string $class
) : self
{
}

Description

Set the CSS class name for the menu group.

This method sets the CSS class name that will be used to style the menu group in the user interface.

Parameters

$class

The CSS class name.

Return

self

The current instance of the class, allowing for method chaining.

5. getMenuItems

Declaration

public function getMenuItems() : AppMenuItem[]
{
}

Description

Get the menu items in this group.

This method returns an array of menu items that belong to this group. The menu items represent the individual actions or links available within the menu group.

Return

AppMenuItem[]

Array of menu items in this group.

6. setMenuItems

Declaration

public function setMenuItems(
    AppMenuItem[] $menuItems
) : self
{
}

Description

Set the menu items for this group.

This method sets an array of menu items for the menu group. Each menu item corresponds to a specific action or link within the group.

Parameters

$menuItems

Array of menu items to be associated with the group.

Return

self

The current instance of the class, allowing for method chaining.

MagicApp\AppMenuItem

Declaration

class AppMenuItem { }

MagicApp\AppModule

Declaration

class AppModule extends MagicObject\MagicObject { }

Constants

const MESSAGE_NO_DATABASE_CONNECTION = 'No database connection provided';
const MESSAGE_NO_RECORD_FOUND = 'No record found';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_TYPE = 'type';
const KEY_LENGTH = 'length';
const KEY_DEFAULT_VALUE = 'defaultValue';
const JSON = 'JSON';
const YAML = 'Yaml';
const ATTR_CHECKED = ' checked="checked"';
const ATTR_SELECTED = ' selected="selected"';
const FIND_OPTION_DEFAULT = 0;
const FIND_OPTION_NO_COUNT_DATA = 1;
const FIND_OPTION_NO_FETCH_DATA = 2;
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Methods

1. nullPropertyList

Declaration

public function nullPropertyList() : array
{
}

Description

Retrieves the list of null properties.

Return

array

The list of properties that are currently null.

2. __construct

Declaration

public function __construct(
    self|array|stdClass|object|null $data = null,
    PicoDatabase|PDO|null $database = null
)
{
}

Description

Constructor.

Initializes the object with the provided data and optionally connects to a database. The constructor can accept different types of data to populate the object and can also accept a PDO connection or a PicoDatabase instance to set up the database connection.

Parameters

$data

Initial data to populate the object. This can be:

$database

A database connection instance, either:

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Loads data into the object.

Parameters

$data

Data to load, which can be another MagicObject, an array, or an object.

Return

self

Returns the current instance for method chaining.

4. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

Parameters

$rawData

Raw INI data

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

5. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

Parameters

$path

File path to the INI file

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

6. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

Parameters

$rawData

YAML string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

7. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

Parameters

$path

File path to the YAML file

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

8. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

Parameters

$rawData

JSON string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

9. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Loads data from a JSON file and processes it based on the provided options.

Parameters

$path

The file path to the JSON file.

$systemEnv

Whether to replace system environment variables in the data (default: false).

$asObject

Whether to return the result as an object instead of an associative array (default: false).

$recursive

Whether to recursively convert all objects into MagicObject instances (default: false).

Return

self

Returns the current instance for method chaining.

Throws

FileNotFoundException

If the specified JSON file does not exist.

10. loadJsonData

Declaration

private function loadJsonData(
    mixed $data,
    bool $asObject,
    bool $recursive
) : self
{
}

Description

Loads processed JSON data and optionally converts it to objects or parses recursively.

Parameters

$data

The processed data to load (array or object).

$asObject

Whether to return the result as an object.

$recursive

Whether to recursively convert all objects into MagicObject instances.

Return

self

Returns the current instance for method chaining.

11. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the read-only state of the object.

When set to read-only, setters will not change the value of its properties, but loadData will still function normally.

Parameters

$readonly

Flag to set the object as read-only

Return

self

Returns the current instance for method chaining.

12. _databaseConnected

Declaration

private function _databaseConnected() : bool
{
}

Description

Check if database is connected or not

Return

bool

Returns true if the database is connected, false otherwise.

13. withDatabase

Declaration

public function withDatabase(
    PicoDatabase $database
) : self
{
}

Description

Set the database connection.

Parameters

$database

Database connection

Return

self

Returns the current instance for method chaining.

14. currentDatabase

Declaration

public function currentDatabase(
    PicoDatabase|null $database = null
) : PicoDatabase|null
{
}

Description

Set or get the current database connection.

If the parameter is not empty, set the current database to the provided value. Otherwise, return the current database or null.

Parameters

$database

Database connection

Return

PicoDatabase|null
15. databaseEntity

Declaration

public function databaseEntity(
    MagicObject|PicoDatabaseEntity|null $databaseEntity = null
) : self|PicoDatabaseEntity
{
}

Description

Set or get the database entity.

If a database entity is provided, it will be set; otherwise, the current database entity will be returned.

Parameters

$databaseEntity

The database entity to set or null to get the current entity.

Return

self|PicoDatabaseEntity

Returns the current instance for method chaining, or the current database entity if no parameter is provided.

16. removePropertyExcept

Declaration

public function removePropertyExcept(
    object|array $sourceData,
    array $propertyNames
) : object|array
{
}

Description

Remove properties except for the specified ones.

Parameters

$sourceData

Data to filter

$propertyNames

Names of properties to retain

Return

object|array

Filtered data

17. save

Declaration

public function save(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Save the current object to the database.

This method persists the current object to the database. If $includeNull is TRUE, all properties of the object, including those with null values, will be saved. If FALSE, only the properties with non-null values will be saved.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

PDOException

If a database error occurs.

18. saveQuery

Declaration

public function saveQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to save data to the database.

This method prepares a query to persist the current object to the database. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only properties with non-null values will be included.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for query construction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

19. select

Declaration

public function select() : self
{
}

Description

Select data from the database.

This method retrieves data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

20. selectAll

Declaration

public function selectAll() : self
{
}

Description

Select all data from the database.

This method retrieves all data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

21. selectQuery

Declaration

public function selectQuery() : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to select data.

This method prepares a query to select data from the database. The query can then be used to execute the retrieval of data manually if needed.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the select query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If a database error occurs.

22. executeNativeQuery

Declaration

protected function executeNativeQuery() : mixed
{
}

Description

Executes a database query based on the parameters and annotations from the caller function.

This method uses reflection to extract the query string and return type from the caller's docblock, binds the provided parameters, and executes the query against the database.

It analyzes the parameters and return type of the caller function to enable dynamic query execution tailored to the specified return type. Supported return types include:

  • void: Returns null.
  • int or integer: Returns the number of affected rows.
  • object or stdClass: Returns a single result as an object.
  • stdClass[]: Returns all results as an array of stdClass objects.
  • array: Returns all results as an associative array.
  • string: Returns the JSON-encoded results.
  • PDOStatement: Returns the prepared statement for further operations if needed.
  • MagicObject and its derived classes: If the return type is a class name or an array of class names, instances of that class will be created for each row fetched.
  • MagicObject[] and its derived classes: Instances of the corresponding class will be created for each row fetched.

Return

mixed

The result based on the return type of the caller function:

Throws

PDOException

If there is an error executing the database query.

InvalidQueryInputException

If there is no query to be executed or if the input is invalid.

InvalidReturnTypeException

If the return type specified in the docblock is invalid or unrecognized.

23. insert

Declaration

public function insert(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Insert data into the database.

This method inserts the current objectΓÇÖs data into the database. If $includeNull is TRUE, properties with null values will also be included in the insert query. If FALSE, only properties with non-null values will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be inserted. If FALSE, only non-null values will be inserted.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the insert query.

24. insertQuery

Declaration

public function insertQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for inserting data.

This method prepares a query to insert data into the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only non-null properties will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the insert query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the insert query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

25. update

Declaration

public function update(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Update data in the database.

This method updates the current object's data in the database. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only properties with non-null values will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be updated. If FALSE, only non-null values will be updated.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the update query.

26. updateQuery

Declaration

public function updateQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for updating data.

This method prepares a query to update data in the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only non-null properties will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the update query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the update query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

27. delete

Declaration

public function delete() : PDOStatement
{
}

Description

Delete data from the database.

This method deletes data associated with the current object from the database.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the delete query.

28. deleteQuery

Declaration

public function deleteQuery() : PicoDatabaseQueryBuilder
{
}

Description

Get the query for deleting data.

This method prepares a query to delete data from the database. It can be used to manually execute the query.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the delete query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

29. startTransaction

Declaration

public function startTransaction() : self
{
}

Description

Starts a database transaction.

This method begins a new database transaction. It delegates the actual transaction initiation to the transactionalCommand method, passing the "start" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error while starting the transaction.

30. commit

Declaration

public function commit() : self
{
}

Description

Commits the current database transaction.

This method commits the current transaction. If successful, it makes all database changes made during the transaction permanent. It delegates to the transactionalCommand method with the "commit" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the commit process.

31. rollback

Declaration

public function rollback() : self
{
}

Description

Rolls back the current database transaction.

This method rolls back the current transaction, undoing all database changes made during the transaction. It calls the transactionalCommand method with the "rollback" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the rollback process.

32. where

Declaration

public function where(
    PicoSpecification $specification
) : PicoDatabasePersistenceExtended
{
}

Description

Get a MagicObject with a WHERE specification.

This method applies a WHERE condition to the database query using the provided specification. The specification is an instance of PicoSpecification which defines the filtering criteria.

Parameters

$specification

The specification to define the WHERE condition.

Return

PicoDatabasePersistenceExtended

Returns an instance of PicoDatabasePersistenceExtended

Throws

NoDatabaseConnectionException

If there is no active database connection.

33. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify properties with null values.

This method tracks properties that are assigned a null value, storing them in a _nullProperties array. If a property is set to null, it is added to the _nullProperties array; if it's set to a non-null value, it is removed from the array.

Parameters

$propertyName

The name of the property to check and modify.

$propertyValue

The value to be assigned to the property.

Return

self

Returns the current instance for method chaining.

34. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Set property value.

Parameters

$propertyName

Property name

$propertyValue

Property value

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

35. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

36. append

Declaration

public function append(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property (alias for push).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

37. unshift

Declaration

public function unshift(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

38. prepend

Declaration

public function prepend(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property (alias for unshift).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

39. pop

Declaration

public function pop(
    string $propertyName
) : mixed
{
}

Description

Remove and return the last element of an array property.

This method removes the last element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the last element will be removed.

Return

mixed

The last element of the array, or null if the property is not an array or doesn't exist.

40. shift

Declaration

public function shift(
    string $propertyName
) : mixed
{
}

Description

Remove and return the first element of an array property.

This method removes the first element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the first element will be removed.

Return

mixed

The first element of the array, or null if the property is not an array or doesn't exist.

41. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get the value of a property.

This method retrieves the value of the specified property. If the property does not exist, it returns null.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property, or null if the property is not set.

42. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed|null
{
}

Description

Get the value of a property or a default value if the property is not set.

This method retrieves the value of the specified property. If the property is not set, the provided default value is returned.

Parameters

$propertyName

The name of the property to retrieve.

$defaultValue

The default value to return if the property is not set.

Return

mixed|null

The value of the property, or the default value if the property is not set.

43. __set

Declaration

public function __set(
    string $propertyName,
    mixed $propertyValue
)
{
}

Description

Set property value (magic setter).

Parameters

$propertyName

Property name

$propertyValue

Property value

44. __get

Declaration

public function __get(
    string $propertyName
) : mixed|null
{
}

Description

Magic method to get the value of a property.

This method is automatically called when an undefined or inaccessible property is accessed. It checks if the property has been set (including null values) using the __isset method and retrieves its value via the get method if it exists.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property if it is set, or null if the property is not set or accessible.

45. __isset

Declaration

public function __isset(
    string $propertyName
) : bool
{
}

Description

Magic method to check if a property is set (including null).

This method is automatically called when checking if an undefined or inaccessible property is set using isset(). It checks if the property exists and is set (even if its value is null).

Parameters

$propertyName

The name of the property to check.

Return

bool

True if the property is set (including null), false otherwise.

46. __unset

Declaration

public function __unset(
    string $propertyName
) : void
{
}

Description

Magic method to unset a property.

This method is automatically called when a property is unset using unset(). It unsets the specified property from the object.

Parameters

$propertyName

The name of the property to unset.

Return

void
47. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copy values from another object to the current instance.

This method copies property values from the provided source object to the current instance. Optionally, a filter can be applied to specify which properties to copy, and whether null values should be included.

Parameters

$source

The source object or data from which values will be copied. If a non-object is provided, this may result in unexpected behavior.

$filter

An optional array of property names to filter which properties are copied. If null, all properties are copied.

$includeNull

Flag indicating whether to include properties with null values. If false, properties with null values will be excluded from the copy.

Return

self

Returns the current instance for method chaining after copying the values.

48. removeValue

Declaration

private function removeValue(
    string $propertyName,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Remove property value and set it to null.

Parameters

$propertyName

Property name

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

49. tableInfo

Declaration

public function tableInfo() : PicoTableInfo
{
}

Description

Retrieve table information for the current instance.

This method retrieves the table information (e.g., schema, columns) associated with the current object. It lazily loads the table information, meaning it will be fetched only once and cached for future calls to improve performance.

Return

PicoTableInfo

Returns an instance of the PicoTableInfo class containing the table schema and other related metadata.

50. defaultValue

Declaration

public function defaultValue(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get default values for properties

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing default values

51. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get the object values

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing the values of the properties

52. valueObject

Declaration

public function valueObject(
    boolean|null $snakeCase = null
) : stdClass
{
}

Description

Get the object value as a specified format

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case; if null, default behavior is used

Return

stdClass

An object representing the value of the instance

53. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get the object value as an associative array

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

array

An associative array representing the object values

54. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get the object value as an associative array with the first letter of each key in upper camel case

Return

array

An associative array with keys in upper camel case

55. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if the JSON naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

56. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if the YAML naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

57. _upperCamel

Declaration

protected function _upperCamel() : bool
{
}

Description

Check if the JSON naming strategy is upper camel case

Return

bool

True if the naming strategy is upper camel case; otherwise, false

58. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if the JSON naming strategy is camel case

Return

bool

True if the naming strategy is camel case; otherwise, false

59. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

60. _isArray

Declaration

private function _isArray(
    mixed $params
) : bool
{
}

Description

Checks if the provided parameter is an array.

This function verifies if the given parameter is set and is of type array. It is a helper method used to validate the type of data before performing any operations on it that require an array.

Parameters

$params

The parameter to check.

Return

bool

Returns true if the parameter is set and is an array, otherwise returns false.

61. _isNotNullAndNotEmpty

Declaration

private function _isNotNullAndNotEmpty(
    mixed $value
) : bool
{
}

Description

Check if a value is not null and not empty

Parameters

$value

The value to check

Return

bool

True if the value is not null and not empty; otherwise, false

62. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get a list of properties

Parameters

$reflectSelf

Flag indicating whether to reflect properties of the current class

$asArrayProps

Flag indicating whether to return properties as an array

Return

array

An array of property names or ReflectionProperty objects

63. listAll

Declaration

public function listAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null
) : PicoPageData
{
}

Description

List all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

64. countData

Declaration

private function countData(
    PicoDatabasePersistence $persist,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable,
    PicoSortable|string|null $sortable,
    int $findOption = 0,
    array|null $result = null
) : int
{
}

Description

Count the data based on specifications

Parameters

$persist

The persistence object

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$findOption

The find option

$result

The result set

Return

int

The count of matching records

65. findOne

Declaration

public function findOne(
    PicoSpecification|null $specification = null,
    PicoSortable|string|null $sortable = null,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record based on specifications

Parameters

$specification

The specification for filtering

$sortable

The sorting criteria

$subqueryMap

An optional map of subqueries

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

66. findAll

Declaration

public function findAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

67. findAllAsc

Declaration

public function findAllAsc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in ascending order

Return

PicoPageData

The paginated data

68. findAllDesc

Declaration

public function findAllDesc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in descending order

Return

PicoPageData

The paginated data

69. findSpecific

Declaration

public function findSpecific(
    string $selected,
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find specific records

Parameters

$selected

The selected field(s)

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

70. countAll

Declaration

public function countAll(
    PicoSpecification|null $specification = null,
    PicoPageable|null $pageable = null,
    PicoSortable|null $sortable = null
) : int|false
{
}

Description

Count all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

int|false

The count of records or false on error

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

71. findAllQuery

Declaration

public function findAllQuery(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null
) : PicoDatabaseQueryBuilder
{
}

Description

Build a query to find all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

PicoDatabaseQueryBuilder

The query builder

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

72. find

Declaration

public function find(
    mixed $params
) : self
{
}

Description

Find one record by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

73. findIfExists

Declaration

public function findIfExists(
    array $params
) : self
{
}

Description

Find one record if it exists by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance. or the current instance if not found

74. findBy

Declaration

private function findBy(
    string $method,
    mixed $params,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap,
    int $findOption
) : PicoPageData
{
}

Description

Find records by specified parameters

Parameters

$method

The method to find by

$params

The parameters for the search

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

75. countBy

Declaration

private function countBy(
    string $method,
    mixed $params
) : int
{
}

Description

Count data from the database.

Parameters

$method

The method used for finding.

$params

The parameters to use for the count.

Return

int

The count of matching records.

Throws

NoDatabaseConnectionException

If there is no database connection.

76. deleteBy

Declaration

private function deleteBy(
    string $method,
    mixed $params
) : int
{
}

Description

Delete records based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

int

The number of deleted records.

Throws

NoDatabaseConnectionException

If there is no database connection.

77. findOneWithPrimaryKeyValue

Declaration

public function findOneWithPrimaryKeyValue(
    mixed $primaryKeyVal,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record using the primary key value.

Parameters

$primaryKeyVal

The primary key value.

$subqueryMap

Optional subquery map for additional queries.

Return

self

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

78. findOneBy

Declaration

private function findOneBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

79. findOneIfExistsBy

Declaration

private function findOneIfExistsBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record if it exists based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance or the current instance if not found.

Throws

NoDatabaseConnectionException

If there is no database connection.

80. deleteOneBy

Declaration

private function deleteOneBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Delete one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

bool

True on success; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

81. existsBy

Declaration

private function existsBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Check if a record exists based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

Return

bool

True if the record exists; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

82. booleanToTextBy

Declaration

private function booleanToTextBy(
    string $propertyName,
    string[] $params
) : string
{
}

Description

Convert a boolean value to text based on the specified property name.

Parameters

$propertyName

The property name to check.

$params

The text representations for true and false.

Return

string

The corresponding text representation.

83. toArrayObject

Declaration

private function toArrayObject(
    array $result,
    bool $passive = false
) : array
{
}

Description

Convert the result to an array of objects.

Parameters

$result

The result set to convert.

$passive

Flag indicating whether the objects are passive.

Return

array

An array of objects.

84. size

Declaration

public function size() : int
{
}

Description

Get the number of properties of the object.

Return

int

The number of properties.

85. __call

Declaration

public function __call(
    string $method,
    mixed $params
) : mixed|null
{
}

Description

Magic method called when a user calls any undefined method. The __call method checks the prefix of the called method and invokes the appropriate method according to its name and parameters.

Method Descriptions:

  • hasValue: Checks if the property has a value.

    • Example: $object->hasValuePropertyName();
  • isset: Checks if the property is set.

    • Example: $object->issetPropertyName();
  • is: Retrieves the property value as a boolean.

    • Example: $isActive = $object->isActive();
  • equals: Checks if the property value equals the given value.

    • Example: $isEqual = $object->equalsPropertyName($value);
  • get: Retrieves the property value.

    • Example: $value = $object->getPropertyName();
  • set: Sets the property value.

    • Example: $object->setPropertyName($value);
  • unset: Unsets the property value.

    • Example: $object->unsetPropertyName();
  • push: Adds array elements to a property at the end.

    • Example: $object->pushPropertyName($newElement);
  • append: Appends array elements to a property at the end.

    • Example: $object->appendPropertyName($newElement);
  • unshift: Adds array elements to a property at the beginning.

    • Example: $object->unshiftPropertyName($newElement);
  • prepend: Prepends array elements to a property at the beginning.

    • Example: $object->prependPropertyName($newElement);
  • pop: Removes the last element from the property.

    • Example: $removedElement = $object->popPropertyName();
  • shift: Removes the first element from the property.

    • Example: $removedElement = $object->shiftPropertyName();
  • findOneBy: Searches for data in the database and returns one record.

    • Example: $record = $object->findOneByPropertyName($value);
    • Requires a database connection.
  • findOneIfExistsBy: Searches for data in the database by any column values and returns one record.

    • Example: $record = $object->findOneIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • deleteOneBy: Deletes data from the database by any column values and returns one record.

    • Example: $deletedRecord = $object->deleteOneByPropertyName($value, $sortable);
    • Requires a database connection.
  • findFirstBy: Searches for data in the database by any column values and returns the first record.

    • Example: $firstRecord = $object->findFirstByColumnName($value);
    • Requires a database connection.
  • findFirstIfExistsBy: Similar to findFirstBy, but returns the first record if it exists.

    • Example: $firstRecord = $object->findFirstIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findLastBy: Searches for data in the database by any column values and returns the last record.

    • Example: $lastRecord = $object->findLastByColumnName($value);
    • Requires a database connection.
  • findLastIfExistsBy: Similar to findLastBy, but returns the last record if it exists.

    • Example: $lastRecord = $object->findLastIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findBy: Searches for multiple records in the database by any column values.

    • Example: $records = $object->findByColumnName($value);
    • Requires a database connection.
  • countBy: Counts data from the database.

    • Example: $count = $object->countByColumnName();
  • existsBy: Checks for data in the database.

    • Example: $exists = $object->existsByColumn($column);
    • Requires a database connection.
  • deleteBy: Deletes data from the database without reading it first.

    • Example: $object->deleteByPropertyName($value);
    • Requires a database connection.
  • booleanToTextBy: Converts a boolean value to "yes/no" or "true/false" based on given parameters.

    • Example: $result = $object->booleanToTextByActive("Yes", "No");
    • If $obj->active is true, $result will be "Yes"; otherwise, it will be "No".
  • startsWith: Checks if the value starts with a given string.

    • Example: $startsWith = $object->startsWithPropertyName("prefix");
  • endsWith: Checks if the value ends with a given string.

    • Example: $endsWith = $object->endsWithPropertyName("suffix");
  • label: Retrieves the label associated with the given property.

    • If the label is not set, it attempts to fetch it from annotations.
    • Example: $label = $object->labelPropertyName();
  • option: Returns the first parameter if the property is set to true or equals 1; otherwise returns the second parameter.

    • Example: $option = $object->optionPropertyName("Yes", "No");
  • notNull: Checks if the specified property is set (not null).

    • Example: $isNotNull = $object->notNullPropertyName();
  • notEmpty: Checks if the specified property is set and not empty.

    • Example: $isNotEmpty = $object->notEmptyPropertyName();
  • notZero: Checks if the specified property is set and not equal to zero.

    • Example: $isNotZero = $object->notZeroPropertyName();
  • notEquals: Checks if the specified property is set and does not equal the given value.

    • Example: $isNotEqual = $object->notEqualsPropertyName($value);

Parameters

$method

Method name

$params

Parameters for the method

Return

mixed|null

The result of the called method, or null if not applicable

86. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

Return

string

A JSON representation of the object.

87. stringifyObject

Declaration

private function stringifyObject(
    self $value,
    bool $snake
) : mixed
{
}

Description

Recursively stringify an object or array of objects.

Parameters

$value

The object to stringify.

$snake

Flag to indicate whether to convert property names to snake_case.

Return

mixed

The stringified object or array.

88. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

The dump method, when supplied with an array, converts it into a friendly YAML format.

Parameters

$inline

The level at which to switch to inline YAML. If NULL, the maximum depth will be used.

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

MagicApp\AppUser

Declaration

class AppUser { }

Description

Class AppUser

Represents a user in the application, encapsulating user properties and behaviors. This class provides access to user data through dynamic getter and setter methods.

Properties

1. userId

Declaration

protected string $userId;

Description

User ID

2. userLevelId

Declaration

protected string $userLevelId;

Description

User level ID

3. languageId

Declaration

protected string $languageId;

Description

Language ID

4. user

Declaration

private MagicObject $user;

Description

User data object encapsulated in a MagicObject.

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $user
)
{
}

Description

Constructor

Initializes the AppUser object with the provided user data object.

Parameters

$user

The user data object to initialize the user.

2. __call

Declaration

public function __call(
    string $method,
    array $args
) : mixed
{
}

Description

Magic method to handle dynamic getter and setter methods.

This method intercepts calls to getter and setter methods that follow the get and set conventions. It delegates these calls to the underlying MagicObject to retrieve or set user properties.

Parameters

$method

The name of the method being called (either a getter or setter).

$args

The arguments passed to the method (if any).

Return

mixed

The value returned by the MagicObject getter/setter method.

Throws

BadMethodCallException

If the method being called is neither a getter nor setter, or if it does not exist in the MagicObject.

3. __toString

Declaration

public function __toString() : string
{
}

Description

String representation of the AppUser object.

This method converts the AppUser object to a string by calling the __toString() method of the encapsulated MagicObject. Typically used for debugging and logging purposes.

Return

string

The string representation of the user data.

MagicApp\AppUserPermission

Declaration

class AppUserPermission { }

Description

Class AppUserPermission

Manages user permissions for various actions within the application. This class provides functionality to check and load user permissions based on roles and modules.

Properties

1. appConfig

Declaration

private SecretObject $appConfig;

Description

Application configuration

2. entity

Declaration

private MagicObject $entity;

Description

Entity representing user roles.

3. currentModule

Declaration

private PicoModule $currentModule;

Description

Current module context.

4. allowedList

Declaration

private boolean $allowedList;

Description

Allowed show list

5. allowedDetail

Declaration

private boolean $allowedDetail;

Description

Allowed show detail

6. allowedCreate

Declaration

private boolean $allowedCreate;

Description

Allowed create

7. allowedUpdate

Declaration

private boolean $allowedUpdate;

Description

Allowed update

8. allowedDelete

Declaration

private boolean $allowedDelete;

Description

Allowed delete

9. allowedApprove

Declaration

private boolean $allowedApprove;

Description

Allowed approve/reject

10. allowedSortOrder

Declaration

private boolean $allowedSortOrder;

Description

Allowed short order

11. allowedBatchAction

Declaration

private boolean $allowedBatchAction;

Description

Allowed batch action

12. initialized

Declaration

private boolean $initialized = false;

Description

Indicates if permissions have been initialized.

13. userLevelId

Declaration

private string $userLevelId;

Description

User level

14. currentUser

Declaration

private MagicObject $currentUser;

Description

Current user

15. userAction

Declaration

private string $userAction;

Description

User action

Methods

1. __construct

Declaration

public function __construct(
    SecretObject $appConfig,
    PicoDatabase $database,
    MagicObject $appUserRole,
    PicoModule $currentModule,
    AppUser $currentUser
)
{
}

Description

Constructor

Initializes the AppUserPermission object with application configuration, database, user role, current module, and current user.

Parameters

$appConfig

The application configuration object.

$database

The database connection object.

$appUserRole

The user role entity.

$currentModule

The current module being accessed.

$currentUser

The current user object.

2. loadPermission

Declaration

public function loadPermission() : void
{
}

Description

Load user permissions.

This method loads the permissions for the current user based on their role and the module being accessed. If the role bypasses permissions, all permissions are granted.

Return

void
3. allowedAccess

Declaration

public function allowedAccess(
    PicoRequestBase $inputGet,
    PicoRequestBase $inputPost
) : boolean
{
}

Description

Check user permission for a given action.

This method checks if the user has permission to perform a specific action, based on input from GET or POST requests.

Parameters

$inputGet

The GET request data.

$inputPost

The POST request data.

Return

boolean

True if the user is allowed to perform the action, false otherwise.

4. checkPermission

Declaration

public function checkPermission(
    PicoRequestBase $inputGet,
    PicoRequestBase $inputPost,
    callable $callbackForbidden
) : void
{
}

Description

Check user permission and trigger a callback if forbidden.

This method checks if the user has permission to perform an action. If not, it triggers the provided callback function to handle the forbidden access.

Parameters

$inputGet

The GET request data.

$inputPost

The POST request data.

$callbackForbidden

The callback function to call when access is forbidden.

Return

void
5. isAllowedTo

Declaration

public function isAllowedTo(
    string $userAction
) : boolean
{
}

Description

Check if user is allowed to perform the given action.

This method checks if the user has permission to perform a specific action based on their roles and permissions.

Parameters

$userAction

The action the user wants to perform.

Return

boolean

True if the user is allowed to perform the action, false otherwise.

6. isAllowedBatchAction

Declaration

public function isAllowedBatchAction() : boolean
{
}

Description

Check if user has permission to edit, activate, deactivate, and delete.

Return

boolean

True if the user has permission for batch actions, false otherwise.

7. isAllowedApprove

Declaration

public function isAllowedApprove() : boolean
{
}

Description

Check if user has permission to approve.

Return

boolean

True if the user has permission to approve, false otherwise.

8. isAllowedList

Declaration

public function isAllowedList() : boolean
{
}

Description

Get allowed show list permission.

Return

boolean

True if the user is allowed to see the list, false otherwise.

9. isAllowedDetail

Declaration

public function isAllowedDetail() : boolean
{
}

Description

Get allowed show detail permission.

Return

boolean

True if the user is allowed to see the detail, false otherwise.

10. isAllowedCreate

Declaration

public function isAllowedCreate() : boolean
{
}

Description

Get allowed create permission.

Return

boolean

True if the user is allowed to create, false otherwise.

11. isAllowedUpdate

Declaration

public function isAllowedUpdate() : boolean
{
}

Description

Get allowed update permission.

Return

boolean

True if the user is allowed to update, false otherwise.

12. isAllowedDelete

Declaration

public function isAllowedDelete() : boolean
{
}

Description

Get allowed delete permission.

Return

boolean

True if the user is allowed to delete, false otherwise.

13. isAllowedSortOrder

Declaration

public function isAllowedSortOrder() : boolean
{
}

Description

Get allowed short order permission.

Return

boolean

True if the user is allowed to perform sorting, false otherwise.

14. getUserLevelId

Declaration

public function getUserLevelId() : string
{
}

Description

Get user level.

Return

string

The user level ID.

15. getCurrentUser

Declaration

public function getCurrentUser() : MagicObject
{
}

Description

Get current user.

Return

MagicObject

The current user object.

16. getUserAction

Declaration

public function getUserAction() : string
{
}

Description

Get user action.

Return

string

The action the user wants to perform.

17. setAllowedSortOrderFalse

Declaration

public function setAllowedSortOrderFalse() : self
{
}

Description

Set allowed sort order to false.

Return

self

The current instance of the class.

MagicApp\CurrentAction

Declaration

class CurrentAction { }

Description

Class CurrentAction

Captures the current user action details, including user information and IP address.

This class is responsible for capturing and providing the details of the current user's action, including the user's identity and IP address. It handles retrieving the user's IP address, accounting for the use of proxy services like Cloudflare, and formatting the current timestamp.

Properties

1. user

Declaration

private string $user;

Description

Current user set by constructor.

2. ip

Declaration

private string $ip;

Description

Current IP address.

Methods

1. __construct

Declaration

public function __construct(
    MagicObject|SecretObject $cfg,
    string $user
)
{
}

Description

Constructor

Initializes the CurrentAction object with the user's information and their IP address. The constructor expects a configuration object for retrieving proxy settings and a string representing the current user.

Parameters

$cfg

Configuration object for getting IP settings.

$user

Current user.

2. getRemoteAddress

Declaration

public function getRemoteAddress(
    MagicObject|SecretObject|null $cfg = null
) : string
{
}

Description

Get remote address.

Retrieves the user's remote IP address. If a proxy service like Cloudflare is used, it fetches the client's IP address from the Cloudflare header. Otherwise, it returns the address from the REMOTE_ADDR server variable.

Parameters

$cfg

Configuration object for proxy settings.

Return

string

The remote address of the user.

3. getTime

Declaration

public function getTime() : string
{
}

Description

Get the current timestamp.

Returns the current time in the format Y-m-d H:i:s for logging or tracking user actions.

Return

string

Formatted current time.

4. getUser

Declaration

public function getUser() : string
{
}

Description

Get the current user.

Returns the current user, which was set during object construction.

Return

string

The current user.

5. getIp

Declaration

public function getIp() : string
{
}

Description

Get the current IP address.

Returns the IP address of the user, which was retrieved during object construction.

Return

string

The current IP address.

MagicApp\EntityApvInfo

Declaration

class EntityApvInfo extends MagicObject\SecretObject { }

Description

Class EntityApvInfo

Represents the approval information entity.

This class encapsulates the approval status information of an entity. It extends from SecretObject to inherit functionality related to security or handling sensitive data, depending on the implementation of the parent class.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. approvalStatus

Declaration

protected string $approvalStatus;

Description

Approval status

This property holds the approval status of the entity. It can represent various states like "pending", "approved", "rejected", etc.

2. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

3. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\EntityInfo

Declaration

class EntityInfo extends MagicObject\SecretObject { }

Description

Class EntityInfo

Represents detailed information about an entity, including its attributes such as name, sorting order, status keys (active, draft), and metadata related to creation, editing, and approval processes.

This class extends SecretObject, implying that it handles sensitive or controlled data, which may include actions and IP addresses associated with entity creation and editing.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. name

Declaration

protected string $name;

Description

The name of the entity.

This property stores the name of the entity, which can be used for display purposes or for identification within the system.

2. sortOrder

Declaration

protected string $sortOrder;

Description

The sort order for the entity.

This property defines the order in which the entity should be sorted in lists or views within the application.

3. active

Declaration

protected string $active;

Description

Indicates whether the entity is active.

This property stores a key or value representing whether the entity is currently active. It may be used to filter active entities in queries or lists.

4. draft

Declaration

protected string $draft;

Description

Indicates whether the entity is in draft state.

This property stores a key or value indicating whether the entity is currently in draft status, which might affect whether it is shown publicly or is editable.

5. adminCreate

Declaration

protected string $adminCreate;

Description

Indicates if the entity was created by an admin.

This property stores a key or value that marks whether the entity was created by an admin, which may influence the permissions or actions available for this entity.

6. adminEdit

Declaration

protected string $adminEdit;

Description

Indicates if the entity was edited by an admin.

This property stores a key or value that marks whether the entity was edited by an admin, providing insight into the entity's history and changes made by admin users.

7. adminAskEdit

Declaration

protected string $adminAskEdit;

Description

The ID of the admin who requested the edit for the entity.

This property stores the ID of the admin user who made a request for the entity to be edited. This can be used to track which admin initiated the request for an edit, providing insight into workflows or permissions.

8. ipCreate

Declaration

protected string $ipCreate;

Description

The IP address from which the entity was created.

This property stores the IP address used during the creation of the entity. It could be used for auditing, logging, or security purposes.

9. ipEdit

Declaration

protected string $ipEdit;

Description

The IP address from which the entity was last edited.

This property stores the IP address used when editing the entity. Similar to ipCreate, it provides tracking of user actions on the entity.

10. ipAskEdit

Declaration

protected string $ipAskEdit;

Description

The IP address from which an edit request was made.

This property tracks the IP address from which a request was made to edit the entity, which could be useful for auditing or monitoring purposes.

11. timeCreate

Declaration

protected string $timeCreate;

Description

The timestamp of when the entity was created.

This property stores the exact time the entity was created in the system. It is generally used for logging, tracking, or sorting entities by their creation time.

12. timeEdit

Declaration

protected string $timeEdit;

Description

The timestamp of when the entity was last edited.

This property records the timestamp when the entity was last modified. It is useful for tracking changes and determining the recency of updates.

13. timeAskEdit

Declaration

protected string $timeAskEdit;

Description

The timestamp of when an edit request was made.

This property stores the timestamp when an admin requested an edit to the entity, allowing for tracking of workflows and approval timelines.

14. waitingFor

Declaration

protected string $waitingFor;

Description

The key or value representing a pending action.

This property stores a key or value that indicates whether there is something waiting for the entity, such as approval or processing.

15. approvalId

Declaration

protected string $approvalId;

Description

The approval ID associated with the entity.

This property stores the ID of the approval process associated with the entity, helping to track the state of the entity within an approval workflow.

16. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

17. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\Field

Declaration

class Field { }

Description

Class Field

Represents a field with dynamic retrieval of values. This class uses the magic method __get to return a string representation of a dynamic value. It provides a static factory method of() to create an instance of the class.

Example usage:

 $field = Field::of();
 echo $field->name;  // Outputs "name"

Methods

1. of

Declaration

public static function of() : Field
{
}

Description

Get an instance of Field.

This static method returns a new instance of the Field class.

Return

Field

A new instance of the Field class.

2. __get

Declaration

public function __get(
    string $value
) : string
{
}

Description

Get a value dynamically using property access.

This magic method is triggered when accessing an undefined or dynamic property. It returns the name of the requested property as a string.

Parameters

$value

The name of the property being accessed.

Return

string

The name of the property.

MagicApp\PicoApproval

Declaration

class PicoApproval { }

Constants

const APPROVAL_APPROVE = 1;
const APPROVAL_REJECT = 2;

Properties

1. entity

Declaration

private MagicObject $entity;

Description

Master entity

2. entityInfo

Declaration

private EntityInfo $entityInfo;

Description

Entity information

3. entityApvInfo

Declaration

private EntityApvInfo $entityApvInfo;

Description

Entity approval information

4. callbackValidation

Declaration

private callable $callbackValidation;

Description

Callback for validation

5. callbackAfterApprove

Declaration

private callable $callbackAfterApprove;

Description

Callback after approval

6. callbackAfterReject

Declaration

private callable $callbackAfterReject;

Description

Callback after rejection

7. currentUser

Declaration

private string $currentUser;

Description

Current user performing the action

8. currentTime

Declaration

private string $currentTime;

Description

Current time of the action

9. currentIp

Declaration

private string $currentIp;

Description

Current IP address of the user

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $entity,
    EntityInfo $entityInfo,
    EntityApvInfo $entityApvInfo,
    callable|null $callbackValidation = null
)
{
}

Description

Constructor

Initializes the approval handler with the provided entity, entity information, approval status information, and an optional validation callback.

This constructor is used to set up the necessary components to manage the approval and rejection process for the given entity. The validation callback, if provided, will be used during the approval process to perform custom validation checks before proceeding with the approval or rejection of the entity.

Parameters

$entity

The master entity being approved or rejected.

$entityInfo

Information about the entity, including metadata like

$entityApvInfo

Information about the entity's approval status

$callbackValidation

Optional validation callback to perform

2. approve

Declaration

public function approve(
    string[] $columnToBeCopied,
    MagicObject|null $entityApv,
    MagicObject|null $entityTrash,
    string $currentUser,
    string $currentTime,
    string $currentIp,
    SetterGetter|null $approvalCallback = null
) : self
{
}

Description

Approve the entity based on its current status and the provided parameters.

This method handles the approval process for the entity, taking actions based on its current status and the type of approval required (e.g., create, update, delete, etc.). It also allows for optional callback actions before and after the approval process. The method updates the entity's fields, such as approval status, draft state, and approval ID, according to the approval type.

The method can approve various actions:

  • CREATE: Sets the entity to a finalized state by removing the draft status and resetting approval ID.
  • ACTIVATE: Approves the activation of the entity.
  • DEACTIVATE: Approves the deactivation of the entity.
  • UPDATE: Approves the update of the entity, copying specified columns from the approval entity.
  • DELETE: Approves the deletion of the entity, optionally moving the data to a trash entity.

    Additionally, if the approvalCallback is provided, it can trigger actions before or after the approval process.

Parameters

$columnToBeCopied

Columns to copy from the approval entity.

$entityApv

Approval entity, used for approval actions like updating or copying.

$entityTrash

Trash entity for storing deleted data.

$currentUser

The user performing the approval.

$currentTime

The current time of the action.

$currentIp

The current IP address of the user performing the action.

$approvalCallback

Optional callback for approval, which can trigger actions before and after the approval process.

Return

self

The current instance, allowing method chaining The current instance of the class, allowing for method chaining.

3. approveActivate

Declaration

private function approveActivate() : void
{
}

Description

Approve activation of the entity.

This method approves the activation of the entity by updating its status to active. It clears any pending actions and preserves the relevant information regarding the last edit request, including admin details, timestamp, and IP address. The entityΓÇÖs status is updated to reflect that it is now active and ready for further actions.

  • The entity's active field is set to true, indicating that the entity is now active.
  • The waitingFor field is set to NOTHING, meaning no further actions are pending.
  • The fields such as adminAskEdit, timeAskEdit, and ipAskEdit retain the values from the previous edit request, ensuring continuity of the last action performed.

Return

void
4. approveDeactivate

Declaration

private function approveDeactivate() : void
{
}

Description

Approve deactivation of the entity.

This method approves the deactivation of the entity by updating its status to inactive. It clears any pending edits and resets the relevant fields such as admin request, timestamp, and IP address of the last request. The entityΓÇÖs status is updated to indicate that it is no longer active and that no further actions are pending.

  • The entity's active field is set to false, indicating deactivation.
  • The waitingFor field is set to NOTHING, meaning no further actions are required.
  • Fields such as adminAskEdit, timeAskEdit, and ipAskEdit are preserved from the previous request, ensuring that these values are not lost during the deactivation process.

Return

void
5. approveDelete

Declaration

public function approveDelete(
    MagicObject $entityTrash,
    string $currentUser,
    string $currentTime,
    string $currentIp,
    SetterGetter|null $approvalCallback = null
) : self
{
}

Description

Approve deletion of the entity.

This method handles the approval and execution of the entity's deletion process. Before performing the deletion, the method can execute custom logic through optional callbacks. The method supports copying the entity's data to a trash or backup table before deletion.

  • If an entityTrash is provided, the entity's data will be copied to the trash table before deletion.
  • The method allows for callback functions to be executed before and after the deletion process, allowing custom logic to be integrated.

Parameters

$entityTrash

Entity to store deleted data

$currentUser

The user performing the deletion

$currentTime

The current time of the action

$currentIp

The current IP address of the user

$approvalCallback

Optional callback for deletion

Return

self

The current instance, allowing method chaining

6. reject

Declaration

public function reject(
    MagicObject $entityApv,
    string|null $currentUser = null,
    string|null $currentTime = null,
    string|null $currentIp = null,
    SetterGetter|null $approvalCallback = null
) : self
{
}

Description

Reject the entity approval.

This method handles the rejection of an entity's approval process. It updates the approval status to "rejected" and performs corresponding actions based on the current status of the entity. The method also supports optional callback functions to be executed before and after the rejection, allowing for custom logic.

  • If the entity is waiting for creation approval, it will be deleted upon rejection.
  • If the entity is waiting for update, activation, deactivation, or deletion approval, it will reset the waiting status and approval ID after rejection.

Parameters

$entityApv

The approval entity to reject

$currentUser

The user performing the rejection (optional)

$currentTime

The current time of the action (optional)

$currentIp

The current IP address of the user (optional)

$approvalCallback

Optional callback for rejection logic

Return

self

The current instance, allowing method chaining

7. validateApproval

Declaration

private function validateApproval(
    MagicObject $entityApv,
    string $currentUser
) : boolean
{
}

Description

Validate the approval process.

This method checks if the approval process is valid by using a callback function, if provided. The callback function allows for custom validation logic to be applied to the entity, the approval entity, and the current user performing the action. If no callback is provided, it simply returns true, indicating that the approval process is valid by default.

Parameters

$entityApv

The approval entity to validate

$currentUser

The user performing the action

Return

boolean

true if validation passes, false otherwise

8. approveUpdate

Declaration

private function approveUpdate(
    MagicObject $entityApv,
    string[] $columnToBeCopied
) : self
{
}

Description

Approve the update of the entity.

This method handles the approval process for updating an entity, copying specified columns from an approval entity, and updating the original entity with those values. It also resets the approval status and clears the approval ID once the update is complete.

Parameters

$entityApv

Approval entity

$columnToBeCopied

Columns to copy from the approval entity

Return

self

The current instance, allowing method chaining

9. getCurrentUser

Declaration

public function getCurrentUser() : string
{
}

Description

Get the current user.

This method returns the username or identifier of the current user.

Return

string

The current user's identifier or name.

10. getCurrentTime

Declaration

public function getCurrentTime() : string
{
}

Description

Get the current time.

This method returns the current timestamp or time when the action was performed.

Return

string

The current time in a formatted string (e.g., 'Y-m-d H:i:s').

11. getCurrentIp

Declaration

public function getCurrentIp() : string
{
}

Description

Get the current IP address.

This method returns the IP address of the user making the request or action.

Return

string

The current IP address of the user.

12. getCallbackAfterApprove

Declaration

public function getCallbackAfterApprove() : callable|null
{
}

Description

Get callback after approval

Return

callable|null
13. getCallbackAfterReject

Declaration

public function getCallbackAfterReject() : callable|null
{
}

Description

Get callback after rejection

Return

callable|null

MagicApp\PicoModule

Declaration

class PicoModule { }

Constants

const HEADER_LOCATION = 'Location: ';

Properties

1. appConfig

Declaration

private SecretObject $appConfig;

Description

App configuration object.

2. targetDirectory

Declaration

private string $targetDirectory = '';

Description

Target directory for module operations.

3. moduleName

Declaration

private string $moduleName = '';

Description

Name of the module.

4. moduleTitle

Declaration

private string $moduleTitle = '';

Description

Title of the module.

5. phpSelf

Declaration

private string $phpSelf = '';

Description

Path of the PHP script that is currently executing.

6. userRole

Declaration

private MagicObject $userRole;

Description

User role object for the current session.

7. allowedModules

Declaration

private string[] $allowedModules = array();

Description

List of allowed modules for the current user role.

8. database

Declaration

private PicoDatabase $database;

Description

Database connection object.

9. appModule

Declaration

private AppModule $appModule;

Description

Application module object.

Methods

1. __construct

Declaration

public function __construct(
    SecretObject $appConfig,
    PicoDatabase $database,
    AppModule|mixed $appModule = null,
    string|null $targetDirectory = null,
    string|null $moduleName = null,
    string|null $moduleTitle = null
)
{
}

Description

Constructor for the PicoModule class.

Parameters

$appConfig

Configuration for the application.

$database

Database connection.

$appModule

Application module object.

$targetDirectory

Target directory for the module.

$moduleName

Name of the module.

$moduleTitle

Title of the module.

2. getUserRole

Declaration

public function getUserRole(
    MagicObject[] $appUserRoles
) : MagicObject
{
}

Description

Get the user role for the current session.

Parameters

$appUserRoles

List of user roles.

Return

MagicObject

The user role object.

3. getAllowedModules

Declaration

public function getAllowedModules(
    MagicObject[] $appUserRoles
) : array
{
}

Description

Get the list of allowed modules for the current user role.

Parameters

$appUserRoles

List of user roles.

Return

array

Array of allowed module IDs.

4. parseRole

Declaration

public function parseRole(
    MagicObject[] $appUserRoles
) : self
{
}

Description

Parse user roles to determine allowed modules and user role.

This method processes the list of user roles and identifies which modules the user is allowed to access based on their roles. It also determines the user's specific role by matching the module name.

The method populates the allowedModules array with the IDs of the modules the user has access to, and sets the userRole property to the role that corresponds to the current module.

Parameters

$appUserRoles

List of user roles to be processed.

Return

self

Returns the current instance for method chaining.

5. getAccess

Declaration

public function getAccess(
    MagicObject $role
) : boolean
{
}

Description

Check if the given role has access to the application.

Parameters

$role

The role to check.

Return

boolean

True if access is allowed, false otherwise.

6. getSelf

Declaration

public function getSelf() : string
{
}

Description

Get the name of the current script.

Return

string

The name of the current PHP script.

7. redirectToItself

Declaration

public function redirectToItself() : void
{
}

Description

Redirect the user to the current script.

Return

void
8. redirectToItselfWithRequireApproval

Declaration

public function redirectToItselfWithRequireApproval() : void
{
}

Description

Redirect the user to the current script with a specific parameter to show require approval only.

Return

void
9. redirectTo

Declaration

public function redirectTo(
    string|null $userAction = null,
    string|null $parameterName = null,
    string|null $parameterValue = null
) : void
{
}

Description

Redirect to a specified URL.

Parameters

$userAction

Current action to perform.

$parameterName

Name of the parameter to append.

$parameterValue

Value of the parameter to append.

Return

void
10. getRedirectUrl

Declaration

public function getRedirectUrl(
    string|null $userAction = null,
    string|null $parameterName = null,
    string|null $parameterValue = null,
    string[]|null $additionalParams = null
) : string
{
}

Description

Generate a redirect URL based on the current context.

Parameters

$userAction

Action to perform.

$parameterName

Parameter name to include in the URL.

$parameterValue

Parameter value to include in the URL.

$additionalParams

Additional parameters to include in the URL.

Return

string

The generated redirect URL.

11. getModuleName

Declaration

public function getModuleName() : string
{
}

Description

Get the name of the module.

Return

string

The module name.

12. getModuleTitle

Declaration

public function getModuleTitle() : string
{
}

Description

Get the title of the module.

Return

string

The module title.

13. getDatabase

Declaration

public function getDatabase() : PicoDatabase
{
}

Description

Get the database connection.

Return

PicoDatabase

The database connection object.

14. getAppModule

Declaration

public function getAppModule() : AppModule|mixed
{
}

Description

Get the application module.

Return

AppModule|mixed

The application module object.

15. getTargetDirectory

Declaration

public function getTargetDirectory() : string
{
}

Description

Get the target directory for the module.

Return

string

The target directory.

MagicApp\UserAction

Declaration

class UserAction { }

Description

Class UserAction

This class handles various actions a user can perform within the system. It provides methods to determine if an action requires approval, handles the approval waiting message, and checks if a next action is specified.

Constants

const SHOW_ALL = 'list';
const INSERT = 'insert';
const CREATE = 'create';
const UPDATE = 'update';
const DELETE = 'delete';
const ACTIVATE = 'activate';
const DEACTIVATE = 'deactivate';
const DETAIL = 'detail';
const APPROVE = 'approve';
const APPROVAL = 'approval';
const REJECT = 'reject';
const SORT_ORDER = 'sort_order';
const USER_ACTION = 'user_action';
const NEXT_ACTION = 'next_action';
const SPECIAL_ACTION = 'special_action';
const EXPORT = 'export';

Methods

1. isRequireApproval

Declaration

public static function isRequireApproval(
    mixed $waitingFor
) : boolean
{
}

Description

Determine if an action requires approval.

Parameters

$waitingFor

The status indicating what is waiting for approval.

Return

boolean

True if approval is required, false otherwise.

2. isRequireNextAction

Declaration

public static function isRequireNextAction(
    mixed $inputGet
) : boolean
{
}

Description

Determine if a next action is specified in the input.

Parameters

$inputGet

The input data containing the next action.

Return

boolean

True if there is a next action, false otherwise.

3. getWaitingForMessage

Declaration

public static function getWaitingForMessage(
    object $appLanguage,
    mixed $waitingFor
) : string
{
}

Description

Get the approval waiting message based on the specified action.

Parameters

$appLanguage

The language object for fetching messages.

$waitingFor

The action waiting for approval.

Return

string

The approval message.

4. getWaitingForText

Declaration

public static function getWaitingForText(
    object $appLanguage,
    mixed $waitingFor
) : string
{
}

Description

Get the short waiting text based on the specified action.

Parameters

$appLanguage

The language object for fetching messages.

$waitingFor

The action waiting for approval.

Return

string

The short approval message.

MagicApp\WaitingFor

Declaration

class WaitingFor { }

Constants

const NOTHING = 0;
const CREATE = 1;
const UPDATE = 2;
const ACTIVATE = 3;
const DEACTIVATE = 4;
const DELETE = 5;
const SORT_ORDER = 6;

Methods

1. getDescription

Declaration

public static function getDescription(
    int $status
) : string
{
}

Description

Get the description of the waiting status.

This method provides a human-readable description of the given waiting status. Each constant in the class represents a specific status, and this method returns the corresponding description based on the value passed.

Parameters

$status

The waiting status constant (e.g., WaitingFor::CREATE).

Return

string

The description of the waiting status.

MagicApp\AppDto\ResponseDto\ButtonFormData

Declaration

class ButtonFormData extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class ButtonFormData

A Data Transfer Object (DTO) that represents the data for an HTML button element within a form. This class encapsulates various attributes commonly used for button elements in HTML forms, including id, class, value, type, and additional custom attributes. It provides getter and setter methods for manipulating these properties, and supports method chaining. This DTO can be used to structure button data for rendering forms or handling form submissions.

Key properties:

  • element: Specifies the HTML element type (e.g., 'button', 'input').
  • type: Defines the button type (e.g., 'submit', 'reset', 'button').
  • class: The CSS class applied to the button.
  • id: The unique identifier for the button.
  • name: The name attribute of the button, typically used in form submission.
  • value: The value attribute of the button, typically used in form submission.
  • textContent: The text content displayed inside the button.
  • attribute: Additional custom attributes to be added to the button element (e.g., 'data-*' attributes).

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. element

Declaration

protected string $element;

Description

The type of the form element (e.g., 'button', 'input').

2. type

Declaration

protected string $type;

Description

The type of the button (e.g., 'submit', 'reset', 'button'). This property can be used for input buttons, but is not currently utilized.

3. class

Declaration

protected string $class;

Description

The CSS class applied to the button element.

4. id

Declaration

protected string $id;

Description

The unique identifier for the button.

5. name

Declaration

protected string $name;

Description

The name of the button, typically used in form submission.

6. value

Declaration

protected string $value;

Description

The value of the button, typically used in form submission.

7. textContent

Declaration

protected string $textContent;

Description

The text content inside the button element.

8. attribute

Declaration

protected array $attribute;

Description

An associative array of additional attributes for the button element.

Methods

1. __construct

Declaration

public function __construct(
    string $element = 'button',
    string|null $type = 'button',
    string|null $class = null,
    string|null $id = null,
    string|null $name = null,
    string|null $value = null,
    string|null $textContent = null
)
{
}

Description

ButtonFormData constructor.

Initializes the properties of the ButtonFormData object. All properties can be optionally initialized by passing values for each one. Default values are provided for each parameter if none are passed.

Parameters

$element

The type of the button form element (default is 'button').

$type

The type of the button (e.g., 'submit', 'reset', 'button') (default is 'button').

$class

The CSS class applied to the button element (default is null).

$id

The unique identifier for the button element (default is null).

$name

The name attribute of the button (default is null).

$value

The value attribute of the button (default is null).

$textContent

The text content inside the button element (default is null).

2. getElement

Declaration

public function getElement() : string
{
}

Description

Get the element type.

Return

string

The type of the form element.

3. setElement

Declaration

public function setElement(
    string $element
) : self
{
}

Description

Set the element type.

Parameters

$element

The element type (e.g., 'button', 'input').

Return

self

The current instance for method chaining.

4. getType

Declaration

public function getType() : string|null
{
}

Description

Get the button type (e.g., 'submit', 'reset', 'button').

Returns the type of the button.

Return

string|null

The type of the button.

5. setType

Declaration

public function setType(
    string $type
) : self
{
}

Description

Set the button type (e.g., 'submit', 'reset', 'button').

Sets the type of the button (such as 'submit', 'reset', or 'button').

Parameters

$type

The button type (e.g., 'submit', 'reset', 'button').

Return

self

The current instance for method chaining.

6. getClass

Declaration

public function getClass() : string
{
}

Description

Get the CSS class applied to the button.

Return

string

The CSS class.

7. setClass

Declaration

public function setClass(
    string $class
) : self
{
}

Description

Set the CSS class for the button.

Parameters

$class

The CSS class to apply to the button.

Return

self

The current instance for method chaining.

8. getId

Declaration

public function getId() : string
{
}

Description

Get the ID of the button.

Return

string

The unique ID of the button.

9. setId

Declaration

public function setId(
    string $id
) : self
{
}

Description

Set the ID of the button.

Parameters

$id

The unique identifier for the button.

Return

self

The current instance for method chaining.

10. getName

Declaration

public function getName() : string
{
}

Description

Get the name of the button.

Return

string

The name attribute of the button.

11. setName

Declaration

public function setName(
    string $name
) : self
{
}

Description

Set the name of the button.

Parameters

$name

The name of the button.

Return

self

The current instance for method chaining.

12. getValue

Declaration

public function getValue() : string
{
}

Description

Get the value of the button.

Return

string

The value attribute of the button.

13. setValue

Declaration

public function setValue(
    string $value
) : self
{
}

Description

Set the value of the button.

Parameters

$value

The value to set for the button.

Return

self

The current instance for method chaining.

14. getTextContent

Declaration

public function getTextContent() : string
{
}

Description

Get the text content of the button.

Return

string

The text content inside the button element.

15. setTextContent

Declaration

public function setTextContent(
    string $textContent
) : self
{
}

Description

Set the text content of the button.

Parameters

$textContent

The text content inside the button element.

Return

self

The current instance for method chaining.

16. getAttribute

Declaration

public function getAttribute() : array
{
}

Description

Get the additional attributes for the button.

Return

array

The associative array of additional attributes.

17. setAttribute

Declaration

public function setAttribute(
    array $attribute
) : self
{
}

Description

Set the additional attributes for the button.

Parameters

$attribute

The associative array of attributes to set for the button.

Return

self

The current instance for method chaining.

18. addAttribute

Declaration

public function addAttribute(
    string $key,
    string $value
) : self
{
}

Description

Add a new attribute to the button. If the attribute key already exists, the value will be updated.

Parameters

$key

The attribute key (e.g., 'data-toggle')

$value

The attribute value (e.g., 'modal')

Return

self

The current instance for method chaining.

19. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

20. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

21. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

22. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

23. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

24. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

25. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ColumnDataDto

Declaration

class ColumnDataDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Data Transfer Object (DTO) representing a column in a tabular data structure.

The ColumnDataDto class encapsulates the properties of a column, including its field name, associated values, data types, and display characteristics. It is designed to facilitate the representation and manipulation of data within a column context, allowing for additional features such as read-only status and visibility control.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. field

Declaration

protected string $field;

Description

The name of the field.

2. label

Declaration

protected string $label;

Description

The label for the field, typically used in user interfaces.

3. value

Declaration

protected mixed $value;

Description

The value associated with the field for display purposes.

4. valueRaw

Declaration

protected mixed $valueRaw;

Description

The raw value associated with the field.

5. type

Declaration

protected string $type;

Description

The data type of the field.

6. readonly

Declaration

protected bool $readonly;

Description

Indicates whether the field is read-only.

7. hidden

Declaration

protected bool $hidden;

Description

Indicates whether the field is hidden from the user interface.

8. valueDraft

Declaration

protected mixed $valueDraft;

Description

The draft value associated with the field for temporary storage.

9. valueDraftRaw

Declaration

protected mixed $valueDraftRaw;

Description

The raw draft value associated with the field.

Methods

1. __construct

Declaration

public function __construct(
    string $field,
    ValueDto $value,
    string $type,
    string $label,
    bool $readonly = false,
    bool $hidden = false,
    ValueDto $valueDraft = null
)
{
}

Description

Constructor to initialize properties of the ColumnDataDto class.

Parameters

$field

The name of the field.

$value

The value associated with the field.

$type

The data type of the field.

$label

The label for the field.

$readonly

Indicates if the field is read-only.

$hidden

Indicates if the field is hidden.

$valueDraft

The draft value associated with the field.

2. getField

Declaration

public function getField() : string
{
}

Description

Get the name of the field.

Return

string

The name of the field.

3. setField

Declaration

public function setField(
    string $field
) : self
{
}

Description

Set the name of the field and return the current instance for method chaining.

Parameters

$field

The name of the field.

Return

self

The current instance for method chaining.

4. getValue

Declaration

public function getValue() : mixed
{
}

Description

Get the value associated with the field.

Return

mixed

The value associated with the field.

5. setValue

Declaration

public function setValue(
    mixed $value
) : self
{
}

Description

Set the value associated with the field and return the current instance for method chaining.

Parameters

$value

The value to associate with the field.

Return

self

The current instance for method chaining.

6. getType

Declaration

public function getType() : string
{
}

Description

Get the type of the field.

Return

string

The type of the field.

7. setType

Declaration

public function setType(
    string $type
) : self
{
}

Description

Set the type of the field and return the current instance for method chaining.

Parameters

$type

The type to set for the field.

Return

self

The current instance for method chaining.

8. getLabel

Declaration

public function getLabel() : string
{
}

Description

Get the label for the field.

Return

string

The label for the field.

9. setLabel

Declaration

public function setLabel(
    string $label
) : self
{
}

Description

Set the label for the field and return the current instance for method chaining.

Parameters

$label

The label to set for the field.

Return

self

The current instance for method chaining.

10. isReadonly

Declaration

public function isReadonly() : bool
{
}

Description

Check if the field is read-only.

Return

bool

True if the field is read-only, otherwise false.

11. setReadonly

Declaration

public function setReadonly(
    bool $readonly
) : self
{
}

Description

Set the read-only status of the field and return the current instance for method chaining.

Parameters

$readonly

Indicates if the field should be read-only.

Return

self

The current instance for method chaining.

12. isHidden

Declaration

public function isHidden() : bool
{
}

Description

Check if the field is hidden.

Return

bool

True if the field is hidden, otherwise false.

13. setHidden

Declaration

public function setHidden(
    bool $hidden
) : self
{
}

Description

Set the hidden status of the field and return the current instance for method chaining.

Parameters

$hidden

Indicates if the field should be hidden.

Return

self

The current instance for method chaining.

14. getValueDraft

Declaration

public function getValueDraft() : mixed
{
}

Description

Get the draft value associated with the field.

Return

mixed

The draft value associated with the field.

15. setValueDraft

Declaration

public function setValueDraft(
    mixed $valueDraft
) : self
{
}

Description

Set the draft value associated with the field and return the current instance for method chaining.

Parameters

$valueDraft

The draft value to associate with the field.

Return

self

The current instance for method chaining.

16. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

17. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

18. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

19. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

20. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

21. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

22. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ColumnDto

Declaration

class ColumnDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class ColumnDto

Represents a data structure for a column in a table or grid-like layout, typically used for displaying rows of data. Each ColumnDto object contains the data for the column (represented by an array of ColumnDataDto objects), as well as associated metadata (represented by a MetadataDto object) which provides additional information about the column, such as its title, type, or other descriptive attributes.

This class is primarily used for managing and structuring data and metadata related to a column in a larger dataset, such as a form, table, or report.

Properties:

  • data: An array of ColumnDataDto objects, each representing a piece of data within the column.
  • metadata: An instance of the MetadataDto class containing additional metadata related to the column.

    Methods:

  • getData(): Retrieves the data associated with the column.
  • setData(array $data): Sets the data for the column and returns the current instance.
  • addData(ColumnDataDto $columnData): Adds a single ColumnDataDto to the data array and returns the current instance.
  • getMetadata(): Retrieves the metadata associated with the column.
  • setMetadata(MetadataDto $metadata): Sets the metadata for the column and returns the current instance.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. data

Declaration

protected ColumnDataDto[] Array of `ColumnDataDto` objects. $data;

Description

Data associated with the row.

2. metadata

Declaration

protected MetadataDto An instance of `MetadataDto`. $metadata;

Description

Metadata associated with the row.

Methods

1. __construct

Declaration

public function __construct()
{
}

Description

ColumnDto constructor.

Initializes the data property as an empty array and creates a new MetadataDto instance for the metadata property.

2. getData

Declaration

public function getData() : ColumnDataDto[]
{
}

Description

Gets the data associated with the column.

Return

ColumnDataDto[]

The array of ColumnDataDto objects.

3. setData

Declaration

public function setData(
    ColumnDataDto[] $data
) : self
{
}

Description

Sets the data for the column.

Parameters

$data

The array of ColumnDataDto objects to set.

Return

self

Returns the current instance for method chaining.

4. addData

Declaration

public function addData(
    ColumnDataDto $columnData
) : self
{
}

Description

Adds a single ColumnDataDto to the data array.

Parameters

$columnData

The ColumnDataDto object to add.

Return

self

Returns the current instance for method chaining.

5. getMetadata

Declaration

public function getMetadata() : MetadataDto
{
}

Description

Gets the metadata associated with the row.

Return

MetadataDto

The metadata associated with the row.

6. setMetadata

Declaration

public function setMetadata(
    MetadataDto $metadata
) : self
{
}

Description

Sets the metadata associated with the row.

Parameters

$metadata

The metadata to set for the column.

Return

self

The current instance for method chaining.

7. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

8. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

9. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

10. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

11. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

12. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

13. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ConstantDto

Declaration

class ConstantDto { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class that defines constants used throughout the application.

The ConstantDto class serves as a container for commonly used string constants that are used across the application. These constants can represent field names, keys, or other values that need to be consistent throughout the codebase.

This pattern ensures that string literals are centralized and avoids the use of "magic strings" in the application code, providing easier maintenance and reducing the risk of typos or inconsistencies.

Constants

const NAME = 'name';
const VALUE = 'value';
const FIELD = 'field';

MagicApp\AppDto\ResponseDto\CreateForm

Declaration

class CreateForm extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class CreateForm

Represents the response structure for a list-based form in a UI. This class holds metadata about the module that the form is associated with, such as the module's ID, name, and title, as well as the status of the request (via the response code and message). It also contains the main data structure (CreateFormData) that holds the filter and data controls for the list.

The CreateForm class is used to encapsulate all necessary information for rendering a form that interacts with a list of data. It provides details about the module's context and feedback about the request, as well as the controls and data required for filtering and displaying the list content in the UI.

Key Features:

  • Hold the metadata about the module (ID, name, and title).
  • Provide the response status and message for request feedback.
  • Contain the CreateFormData structure, which manages the list's filter and data controls.
  • Allow easy access to the response details and the data form structure.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. namespace

Declaration

protected string $namespace;

Description

The namespace where the module is located, such as "/", "/admin", "/supervisor", etc.

2. moduleId

Declaration

protected string $moduleId;

Description

The ID of the module associated with the data.

3. moduleName

Declaration

protected string $moduleName;

Description

The name of the module associated with the data.

4. moduleTitle

Declaration

protected string $moduleTitle;

Description

The title of the module associated with the data.

5. responseCode

Declaration

protected string $responseCode;

Description

The response code indicating the status of the request.

6. responseMessage

Declaration

protected string $responseMessage;

Description

A message providing additional information about the response.

7. data

Declaration

protected CreateFormData $data;

Description

The main data structure containing the list form.

Methods

1. getNamespace

Declaration

public function getNamespace() : string
{
}

Description

Get the namespace where the module is located.

Return

string

The namespace.

2. setNamespace

Declaration

public function setNamespace(
    string $namespace
) : self
{
}

Description

Set the namespace where the module is located.

Parameters

$namespace

The namespace to set.

Return

self

The current instance for method chaining.

3. getModuleId

Declaration

public function getModuleId() : string
{
}

Description

Get the module ID associated with the data.

Return

string

The module ID.

4. setModuleId

Declaration

public function setModuleId(
    string $moduleId
) : self
{
}

Description

Set the module ID associated with the data.

Parameters

$moduleId

The module ID to set.

Return

self

The current instance for method chaining.

5. getModuleName

Declaration

public function getModuleName() : string
{
}

Description

Get the module name associated with the data.

Return

string

The module name.

6. setModuleName

Declaration

public function setModuleName(
    string $moduleName
) : self
{
}

Description

Set the module name associated with the data.

Parameters

$moduleName

The module name to set.

Return

self

The current instance for method chaining.

7. getModuleTitle

Declaration

public function getModuleTitle() : string
{
}

Description

Get the module title associated with the data.

Return

string

The module title.

8. setModuleTitle

Declaration

public function setModuleTitle(
    string $moduleTitle
) : self
{
}

Description

Set the module title associated with the data.

Parameters

$moduleTitle

The module title to set.

Return

self

The current instance for method chaining.

9. getResponseCode

Declaration

public function getResponseCode() : string|null
{
}

Description

Get the response code indicating the status of the request.

Return

string|null

The response code.

10. setResponseCode

Declaration

public function setResponseCode(
    string|null $responseCode
) : self
{
}

Description

Set the response code indicating the status of the request.

Parameters

$responseCode

The response code to set.

Return

self

The current instance for method chaining.

11. getResponseMessage

Declaration

public function getResponseMessage() : string|null
{
}

Description

Get the response message providing additional information about the response.

Return

string|null

The response message.

12. setResponseMessage

Declaration

public function setResponseMessage(
    string|null $responseMessage
) : self
{
}

Description

Set the response message providing additional information about the response.

Parameters

$responseMessage

The response message to set.

Return

self

The current instance for method chaining.

13. getData

Declaration

public function getData() : CreateFormData|null
{
}

Description

Get the main data structure containing the list form.

Return

CreateFormData|null

The data structure for the form.

14. setData

Declaration

public function setData(
    CreateFormData|null $data
) : self
{
}

Description

Set the main data structure containing the list form.

Parameters

$data

The data structure to set.

Return

self

The current instance for method chaining.

15. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

16. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

17. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

18. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

19. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

20. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

21. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\CreateFormData

Declaration

class CreateFormData extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class CreateFormData

Represents a data structure for creating form filters or input elements in the UI. This class handles the configuration for a filter or form input, such as the filter's label, field name, input type, default value, and other attributes.

The class contains a column property, which is an array of InputFormData objects. Each InputFormData represents a column or field in the form, such as a filter or search field.

Properties:

  • column: An array of InputFormData objects, each representing a column or input field in the form.
  • button: An array of ButtonFormData objects, each representing a button in the form.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. column

Declaration

protected InputFormData[] Array of `InputFormData` objects. $column;

Description

The columns or input fields associated with the form. This property holds an array of InputFormData objects, each representing a column or filter element.

2. button

Declaration

protected ButtonFormData[] Array of `ButtonFormData` objects. $button;

Description

The buttons associated with the form. This property holds an array of ButtonFormData objects, each representing a button within the form.

Methods

1. __construct

Declaration

public function __construct()
{
}

Description

CreateFormData constructor.

Initializes the column property as an empty array. Initializes the button property as an empty array.

2. getColumn

Declaration

public function getColumn() : InputFormData[]
{
}

Description

Gets the array of InputFormData objects representing the columns or input fields.

Return

InputFormData[]

The array of InputFormData objects representing the columns.

3. setColumn

Declaration

public function setColumn(
    InputFormData[] $column
) : self
{
}

Description

Sets the array of InputFormData objects representing the columns or input fields.

Parameters

$column

The array of InputFormData objects to set.

Return

self

Returns the current instance for method chaining.

4. addColumn

Declaration

public function addColumn(
    InputFormData $inputFormData
) : self
{
}

Description

Adds a single InputFormData object to the column array.

This method allows you to append one InputFormData object at a time to the column property.

Parameters

$inputFormData

The InputFormData object to add to the column.

Return

self

Returns the current instance for method chaining.

5. getButton

Declaration

public function getButton() : ButtonFormData[]
{
}

Description

Gets the array of ButtonFormData objects associated with the form.

Return

ButtonFormData[]

The array of ButtonFormData objects.

6. setButton

Declaration

public function setButton(
    ButtonFormData[] $button
) : self
{
}

Description

Sets the array of ButtonFormData objects representing the buttons in the form.

Parameters

$button

The array of ButtonFormData objects to set.

Return

self

Returns the current instance for method chaining.

7. addButton

Declaration

public function addButton(
    ButtonFormData $buttonFormData
) : self
{
}

Description

Adds a single ButtonFormData object to the button array.

Parameters

$buttonFormData

The ButtonFormData object to add to the button array.

Return

self

Returns the current instance for method chaining.

8. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

9. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

10. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

11. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

12. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

13. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

14. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\DataMap

Declaration

class DataMap extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class DataMap

Represents a mapping of fields to their corresponding values or definitions. This class contains a field name and an associative array that defines how the field is mapped, allowing for flexible data transformation and retrieval.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. field

Declaration

protected string $field;

Description

The name of the field being mapped.

2. map

Declaration

protected array $map;

Description

An associative array representing the mapping of the field.

Methods

1. __construct

Declaration

public function __construct(
    string $field,
    array $map
)
{
}

Description

Constructor for initializing a DataMap instance.

Parameters

$field

The name of the field.

$map

An associative array defining the mapping for the field.

2. getField

Declaration

public function getField() : string
{
}

Description

Get the name of the field.

Return

string

The name of the field.

3. setField

Declaration

public function setField(
    string $field
) : self
{
}

Description

Set the name of the field.

Parameters

$field

The name of the field.

Return

self

The instance of this class for method chaining.

4. getMap

Declaration

public function getMap() : array
{
}

Description

Get the mapping for the field.

Return

array

The mapping for the field.

5. setMap

Declaration

public function setMap(
    array $map
) : self
{
}

Description

Set the mapping for the field.

Parameters

$map

The mapping for the field.

Return

self

The instance of this class for method chaining.

6. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

7. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

8. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

9. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

10. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

11. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

12. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\DetailDataDto

Declaration

class DetailDataDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class DetailDataDto

Represents the data structure for a table, including column titles and rows. This class manages the titles of column, a data map, and the rows of data represented as RowDto instances. It provides methods for appending titles, data maps, and rows, as well as resetting these structures.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. primaryKeyName

Declaration

protected string[] $primaryKeyName;

Description

The name of the primary key in the data structure.

2. primaryKeyDataType

Declaration

protected string[] $primaryKeyDataType;

Description

An associative array mapping primary key names to their data types.

3. column

Declaration

protected ColumnDto $column;

Description

An array of column, each represented as a ColumnDto.

4. dataControl

Declaration

protected ButtonFormData[] $dataControl;

Description

Data control

Methods

1. __construct

Declaration

public function __construct()
{
}

Description

Initializes the object and sets up the necessary properties. This constructor creates a new instance of ColumnDto for the column property and initializes an empty array for the dataControl property.

2. getPrimaryKeyName

Declaration

public function getPrimaryKeyName() : string[]|null
{
}

Description

Get the name of the primary key in the data structure.

Return

string[]|null

The name of the primary key.

3. setPrimaryKeyName

Declaration

public function setPrimaryKeyName(
    string[]|null $primaryKeyName
) : self
{
}

Description

Set the name of the primary key in the data structure.

Parameters

$primaryKeyName

The name of the primary key.

Return

self

The current instance for method chaining.

4. addPrimaryKeyName

Declaration

public function addPrimaryKeyName(
    string $primaryKeyName,
    string $primaryKeyDataType
) : self
{
}

Description

Add a primary key name and its data type to the list of primary keys.

This method initializes the primary key name and data type properties as arrays if they haven't been set, then appends the new primary key name and its corresponding data type to the lists.

Parameters

$primaryKeyName

The primary key name to add.

$primaryKeyDataType

The primary key data type to add.

Return

self

The instance of this class for method chaining.

5. addData

Declaration

public function addData(
    string $field,
    mixed $value,
    string $type,
    string $label,
    bool $readonly,
    bool $hidden,
    mixed $valueDraft
) : self
{
}

Description

Append a row of data to the table.

This method adds a new row to the internal column collection using the provided parameters to create a ColumnDto instance.

Parameters

$field

The name of the field.

$value

The value associated with the field.

$type

The type of the field.

$label

The label for the field.

$readonly

Indicates if the field is read-only.

$hidden

Indicates if the field is hidden.

$valueDraft

The draft value associated with the field.

Return

self

The current instance for method chaining.

6. getColumn

Declaration

public function getColumn() : ColumnDto
{
}

Description

Get an array of column, each represented as a ColumnDto.

Return

ColumnDto

The column in the data structure.

7. setColumn

Declaration

public function setColumn(
    ColumnDto[] $column
) : self
{
}

Description

Set an array of column, each represented as a ColumnDto.

Parameters

$column

An array of column to set.

Return

self

The current instance for method chaining.

8. getPrimaryKeyDataType

Declaration

public function getPrimaryKeyDataType() : string[]
{
}

Description

Retrieves the associative array mapping primary key names to their data types.

This method returns the current mapping of primary key names to their associated data types as an associative array, where the keys are the primary key names and the values are their respective data types.

Return

string[]

An associative array where the keys are primary key names and the values are data types.

9. setPrimaryKeyDataType

Declaration

public function setPrimaryKeyDataType(
    string[] $primaryKeyDataType
) : self
{
}

Description

Sets an associative array mapping primary key names to their data types.

This method allows setting or updating the mapping of primary key names to their respective data types. The argument should be an associative array where each key represents a primary key name and the corresponding value is the data type.

Parameters

$primaryKeyDataType

An associative array mapping primary key names to their data types.

Return

self

Returns the current instance for method chaining.

10. addPrimaryKeyDataType

Declaration

public function addPrimaryKeyDataType(
    string $name,
    string $type
) : self
{
}

Description

Appends or updates the data type for a specific primary key name.

This method allows appending a new primary key name and its associated data type to the existing mapping or updating the data type of an existing primary key name. The primary key name is specified as the $name argument, and the data type is specified as the $type argument.

Parameters

$name

The primary key name to be added or updated in the mapping.

$type

The data type to be associated with the primary key name.

Return

self

Returns the current instance for method chaining.

11. addDataControl

Declaration

public function addDataControl(
    ButtonFormData $dataControl
) : self
{
}

Description

Adds a ButtonFormData object to the internal collection of data controls. This method stores the given data control for further use or processing.

Parameters

$dataControl

The ButtonFormData object to be added to the collection.

Return

self

Returns the current object instance for method chaining.

12. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

13. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

14. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

15. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

16. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

17. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

18. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\DetailDto

Declaration

class DetailDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Data Transfer Object (DTO) for displaying records in a table format.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. namespace

Declaration

protected string $namespace;

Description

The namespace where the module is located, such as "/", "/admin", "/supervisor", etc.

2. moduleId

Declaration

protected string $moduleId;

Description

The ID of the module associated with the data.

3. moduleName

Declaration

protected string $moduleName;

Description

The name of the module associated with the data.

4. moduleTitle

Declaration

protected string $moduleTitle;

Description

The title of the module associated with the data.

5. responseCode

Declaration

protected string $responseCode;

Description

The response code indicating the status of the request.

6. responseMessage

Declaration

protected string $responseMessage;

Description

A message providing additional information about the response.

7. data

Declaration

protected DetailDataDto $data;

Description

The main data structure containing the list of items.

Methods

1. __construct

Declaration

public function __construct(
    string|null $responseCode,
    string|null $responseMessage,
    DetailDataDto $data
)
{
}

Description

Constructor for initializing the DetailDto instance.

Parameters

$responseCode

The response code.

$responseMessage

The response message.

$data

The main data structure.

2. getNamespace

Declaration

public function getNamespace() : string
{
}

Description

Get the namespace where the module is located.

Return

string

The namespace.

3. setNamespace

Declaration

public function setNamespace(
    string $namespace
) : self
{
}

Description

Set the namespace where the module is located.

Parameters

$namespace

The namespace to set.

Return

self

The current instance for method chaining.

4. getData

Declaration

public function getData() : DetailDataDto|null
{
}

Description

Get the main data structure containing the detail columns.

Return

DetailDataDto|null

The detail data structure.

5. addData

Declaration

public function addData(
    string $field,
    ValueDto $value,
    string|null $type = null,
    string|null $label = null,
    bool $readonly = false,
    bool $hidden = false,
    ValueDto|null $valueDraft = null
) : self
{
}

Description

Add a new detail column.

This method creates a new DetailColumnDto and appends it to the detail data structure.

Parameters

$field

The field associated with the detail.

$value

The value associated with the detail.

$type

The type of the value.

$label

The label describing the detail.

$readonly

Whether the detail is readonly.

$hidden

Whether the detail is hidden.

$valueDraft

The value associated with the draft data.

Return

self

The instance of this class for method chaining.

6. addPrimaryKeyName

Declaration

public function addPrimaryKeyName(
    string $primaryKeyName,
    string $primaryKeyDataType
) : self
{
}

Description

Add a primary key name and its data type to the list of primary keys.

This method initializes the primary key name and data type properties as arrays if they haven't been set, then appends the new primary key name and its corresponding data type to the lists.

Parameters

$primaryKeyName

The primary key name to add.

$primaryKeyDataType

The primary key data type to add.

Return

self

The instance of this class for method chaining.

7. setMetadata

Declaration

public function setMetadata(
    MetadataDto $metadata
) : self
{
}

Description

Set metadata associated with the row.

Parameters

$metadata

Metadata associated with the row.

Return

self

The current instance for method chaining.

8. addDataControl

Declaration

public function addDataControl(
    ButtonFormData $dataControl
) : self
{
}

Description

Adds a data control to the data object. This function allows for the addition of a data control to be managed by the current object.

Parameters

$dataControl

The ButtonFormData object containing the data control to be added.

Return

self

Returns the current object instance for method chaining.

9. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

10. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

11. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

12. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

13. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

14. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

15. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\InputFormData

Declaration

class InputFormData extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class InputFormData

Represents a filter or form input element in a UI, typically used in a search or filter form. This class stores information about the filter's configuration, such as the label, field name, input type, default value, and other attributes that define how the filter will be displayed and interacted with in the UI.

It supports various input types such as text, number, date, datetime, select, and button, allowing flexibility in how the filter is rendered. Additionally, it provides methods for setting and retrieving the filter properties, and supports chaining of setter methods.

Properties:

  • label: The label that will be displayed next to the filter input element.
  • field: The field name in the data model to which this filter corresponds.
  • name: A unique identifier for the filter in the UI.
  • id: A unique identifier for the filter control, used for DOM manipulation.
  • element: The type of HTML input element used for the filter (e.g., "text", "select").
  • attribute: An array of additional HTML attributes to apply to the filter element (e.g., class, style).
  • textContent: The text label for button elements (e.g., "Apply", "Reset").
  • selectOption: The select options for select input elements, represented as a SelectOptionDto object.
  • defaultValue: The default value for the filter input, which is pre-filled when the form is loaded.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. label

Declaration

protected string $label;

Description

The label that will be displayed next to the filter input element. This is the text that describes the purpose of the filter field.

2. field

Declaration

protected string $field;

Description

The field name that this filter corresponds to in the data model. Typically, this is the name of the property or column being filtered in the backend.

3. name

Declaration

protected string $name;

Description

A unique name or identifier for this filter, used to reference the filter in the user interface.

4. id

Declaration

protected string $id;

Description

The unique identifier for the filter control element, typically used for DOM element identification. This is often used in JavaScript to manipulate or target the element.

5. element

Declaration

protected string $element;

Description

The type of HTML input element used for the filter. The available types include:

  • "text": For text input fields.
  • "number": For numeric input fields.
  • "date": For date input fields.
  • "datetime": For date-time input fields.
  • "checkbox": For checkbox input fields.
  • "select": For drop-down select lists.
  • "button": For button elements, typically used for applying or resetting the filter.
6. attribute

Declaration

protected array $attribute;

Description

An associative array of HTML attributes to apply to the filter element. This can include attributes like "class", "id", "style", "placeholder", and others to customize the appearance or behavior.

7. textContent

Declaration

protected string $textContent;

Description

The text content for button elements, used to define the button's label (e.g., "Apply", "Reset"). This is applicable when the element type is "button".

8. selectOption

Declaration

protected SelectOptionDto $selectOption;

Description

Select option for "select" input elements, represented by a SelectOptionDto object. This defines the options available for the user to choose from in a select input field.

9. defaultValue

Declaration

protected mixed $defaultValue;

Description

The default value for the filter input. This is the value that will be pre-filled or selected when the form is loaded.

Methods

1. getLabel

Declaration

public function getLabel() : string
{
}

Description

Get the label for the filter.

Return

string

The label of the filter.

2. setLabel

Declaration

public function setLabel(
    string $label
) : self
{
}

Description

Set the label for the filter.

Parameters

$label

The label to set.

Return

self

Returns the current instance for chaining.

3. getField

Declaration

public function getField() : string
{
}

Description

Get the field name associated with this filter.

Return

string

The field name of the filter.

4. setField

Declaration

public function setField(
    string $field
) : self
{
}

Description

Set the field name associated with this filter.

Parameters

$field

The field name to set.

Return

self

Returns the current instance for chaining.

5. getName

Declaration

public function getName() : string
{
}

Description

Get the unique name or identifier for this filter.

Return

string

The name of the filter.

6. setName

Declaration

public function setName(
    string $name
) : self
{
}

Description

Set the unique name or identifier for this filter.

Parameters

$name

The name to set.

Return

self

Returns the current instance for chaining.

7. getId

Declaration

public function getId() : string
{
}

Description

Get the unique identifier for the filter control element.

Return

string

The ID of the filter control.

8. setId

Declaration

public function setId(
    string $id
) : self
{
}

Description

Set the unique identifier for the filter control element.

Parameters

$id

The ID to set.

Return

self

Returns the current instance for chaining.

9. getElement

Declaration

public function getElement() : string
{
}

Description

Get the type of HTML input element used for the filter.

Return

string

The input element type.

10. setElement

Declaration

public function setElement(
    string $element
) : self
{
}

Description

Set the type of HTML input element used for the filter.

Parameters

$element

The element type to set.

Return

self

Returns the current instance for chaining.

11. getAttribute

Declaration

public function getAttribute() : array
{
}

Description

Get the HTML attributes for the filter element.

Return

array

The attributes of the filter.

12. setAttribute

Declaration

public function setAttribute(
    array $attribute
) : self
{
}

Description

Set the HTML attributes for the filter element.

Parameters

$attribute

The attributes to set.

Return

self

Returns the current instance for chaining.

13. getTextContent

Declaration

public function getTextContent() : string
{
}

Description

Get the text content for button elements.

Return

string

The text content of the button (e.g., "Apply", "Reset").

14. setTextContent

Declaration

public function setTextContent(
    string $textContent
) : self
{
}

Description

Set the text content for button elements.

Parameters

$textContent

The button text content to set.

Return

self

Returns the current instance for chaining.

15. getSelectOption

Declaration

public function getSelectOption() : SelectOptionDto
{
}

Description

Get the select option associated with the filter.

Return

SelectOptionDto

The select option.

16. setSelectOption

Declaration

public function setSelectOption(
    SelectOptionDto $selectOption
) : self
{
}

Description

Set the select option for the filter.

Parameters

$selectOption

The select option to set.

Return

self

Returns the current instance for chaining.

17. getDefaultValue

Declaration

public function getDefaultValue() : mixed
{
}

Description

Get the default value for the filter input.

Return

mixed

The default value of the filter.

18. setDefaultValue

Declaration

public function setDefaultValue(
    mixed $defaultValue
) : self
{
}

Description

Set the default value for the filter input.

Parameters

$defaultValue

The default value to set.

Return

self

Returns the current instance for chaining.

19. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

20. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

21. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

22. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

23. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

24. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

25. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ListDataControl

Declaration

class ListDataControl extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class ListDataControl

Represents a filter control element for use in a list filter UI. This class holds the metadata and attributes for the filter input element, including its label, field name, and the associated HTML attributes and text content.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. field

Declaration

protected string $field;

Description

The field name that this filter corresponds to in the data model. This is typically the name of the property or column being filtered.

2. name

Declaration

protected string $name;

Description

A unique name or identifier for this filter, used to reference the filter in the UI.

3. id

Declaration

protected string $id;

Description

The unique identifier for the filter control, typically used for DOM element identification.

4. element

Declaration

protected string $element;

Description

The type of HTML input element used for the filter. This can be one of the following types:

  • "text": For text input fields.
  • "number": For numeric input fields.
  • "date": For date input fields.
  • "datetime": For date-time input fields.
  • "checkbox": For checkbox input fields.
  • "select": For drop-down select lists.
  • "button": For button elements, typically used for submitting or resetting the filter.
5. attribute

Declaration

protected array $attribute;

Description

An associative array of HTML attributes to apply to the filter element. This can include attributes like "class", "id", "style", "placeholder", etc.

6. textContent

Declaration

protected string $textContent;

Description

The text content for button elements, used to define the button's label (e.g., "Apply", "Reset").

Methods

1. getField

Declaration

public function getField() : string
{
}

Description

Gets the field name associated with the filter.

Return

string

The field name.

2. setField

Declaration

public function setField(
    string $field
) : self
{
}

Description

Sets the field name associated with the filter.

Parameters

$field

The field name to set.

Return

self

Returns the current instance for chaining.

3. getName

Declaration

public function getName() : string
{
}

Description

Gets the unique name for the filter.

Return

string

The unique name.

4. setName

Declaration

public function setName(
    string $name
) : self
{
}

Description

Sets the unique name for the filter.

Parameters

$name

The name to set.

Return

self

Returns the current instance for chaining.

5. getId

Declaration

public function getId() : string
{
}

Description

Gets the unique identifier for the filter control.

Return

string

The ID.

6. setId

Declaration

public function setId(
    string $id
) : self
{
}

Description

Sets the unique identifier for the filter control.

Parameters

$id

The ID to set.

Return

self

Returns the current instance for chaining.

7. getElement

Declaration

public function getElement() : string
{
}

Description

Gets the type of HTML element used for the filter input.

Return

string

The input element type (e.g., "text", "number").

8. setElement

Declaration

public function setElement(
    string $element
) : self
{
}

Description

Sets the type of HTML element used for the filter input.

Parameters

$element

The element type to set.

Return

self

Returns the current instance for chaining.

9. getAttribute

Declaration

public function getAttribute() : array
{
}

Description

Gets the HTML attributes associated with the filter element.

Return

array

The array of HTML attributes.

10. setAttribute

Declaration

public function setAttribute(
    array $attribute
) : self
{
}

Description

Sets the HTML attributes associated with the filter element.

Parameters

$attribute

The attributes to set.

Return

self

Returns the current instance for chaining.

11. getTextContent

Declaration

public function getTextContent() : string
{
}

Description

Gets the text content for button elements.

Return

string

The text content for button elements.

12. setTextContent

Declaration

public function setTextContent(
    string $textContent
) : self
{
}

Description

Sets the text content for button elements.

Parameters

$textContent

The text content to set.

Return

self

Returns the current instance for chaining.

13. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

14. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

15. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

16. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

17. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

18. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

19. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ListDataDto

Declaration

class ListDataDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class ListDataDto

Represents the data structure for a table, including column titles and row. This class manages the titles of columns, a data map, and the row of data represented as RowDto instances. It provides methods for appending titles, data maps, and row, as well as resetting these structures.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. title

Declaration

protected ListDataTitleDto[] $title;

Description

An array of column titles for the data table.

2. dataMap

Declaration

protected DataMap[] $dataMap;

Description

An array of data maps for the data table.

3. primaryKeyName

Declaration

protected string[] $primaryKeyName;

Description

The name of the primary key in the data structure.

4. primaryKeyDataType

Declaration

protected string[] $primaryKeyDataType;

Description

An associative array mapping primary key names to their data types.

5. page

Declaration

protected PageDto $page;

Description

Current page

6. row

Declaration

protected RowDto[] $row;

Description

An array of row, each represented as a RowDto.

7. dataControl

Declaration

protected ButtonFormData[] $dataControl;

Description

Data control

Methods

1. __construct

Declaration

public function __construct()
{
}

Description

Initializes the object and sets up the necessary properties. This constructor initializes the row property as an empty array and the dataControl property as an empty array.

2. getPrimaryKeyName

Declaration

public function getPrimaryKeyName() : string[]|null
{
}

Description

Get the name of the primary key in the data structure.

Return

string[]|null
3. setPrimaryKeyName

Declaration

public function setPrimaryKeyName(
    string[]|null $primaryKeyName
) : self
{
}

Description

Set the name of the primary key in the data structure.

Parameters

$primaryKeyName

The name of the primary key.

Return

self

The current instance for method chaining.

4. addPrimaryKeyName

Declaration

public function addPrimaryKeyName(
    string $primaryKeyName,
    string $primaryKeyDataType
) : self
{
}

Description

Add a primary key name and its data type to the list of primary keys.

This method initializes the primary key name and data type properties as arrays if they haven't been set, then appends the new primary key name and its corresponding data type to the lists.

Parameters

$primaryKeyName

The primary key name to add.

$primaryKeyDataType

The primary key data type to add.

Return

self

The instance of this class for method chaining.

5. addTitle

Declaration

public function addTitle(
    ListDataTitleDto $title
) : self
{
}

Description

Append a column title to the table.

Parameters

$title

The title to append.

Return

self

The current instance for method chaining.

6. addDataMap

Declaration

public function addDataMap(
    DataMap $dataMap
) : self
{
}

Description

Append a data map to the table.

Parameters

$dataMap

The data map to append.

Return

self

The current instance for method chaining.

7. addData

Declaration

public function addData(
    MagicObject $data,
    MetadataDto $metadata
) : self
{
}

Description

Append a row of data to the table.

This method adds a new row to the internal row collection using the provided MagicObject as data along with the associated MetadataDto.

Parameters

$data

The row data to append.

$metadata

The metadata associated with the row data.

Return

self

The current instance for method chaining.

8. getTitle

Declaration

public function getTitle() : ListDataTitleDto[]
{
}

Description

Get an array of column titles for the data table.

Return

ListDataTitleDto[]

The column titles.

9. resetTitle

Declaration

public function resetTitle() : self
{
}

Description

Reset the column titles to an empty array.

Return

self

The current instance for method chaining.

10. getDataMap

Declaration

public function getDataMap() : DataMap[]
{
}

Description

Get the data map for the table.

Return

DataMap[]

The data map.

11. resetDataMap

Declaration

public function resetDataMap() : self
{
}

Description

Reset the data map to an empty array.

Return

self

The current instance for method chaining.

12. getRow

Declaration

public function getRow() : RowDto[]
{
}

Description

Get an array of row for the data table.

Return

RowDto[]

The row of data.

13. resetRow

Declaration

public function resetRow() : self
{
}

Description

Reset the row to an empty array.

Return

self

The current instance for method chaining.

14. getPage

Declaration

public function getPage() : PageDto
{
}

Description

Get current page

Return

PageDto
15. setPage

Declaration

public function setPage(
    PageDto $page
) : self
{
}

Description

Set current page

Parameters

$page

Current page

Return

self
16. getPrimaryKeyDataType

Declaration

public function getPrimaryKeyDataType() : string[]
{
}

Description

Get an associative array mapping primary key names to their data types.

Return

string[]
17. setPrimaryKeyDataType

Declaration

public function setPrimaryKeyDataType(
    string[] $primaryKeyDataType
) : self
{
}

Description

Set an associative array mapping primary key names to their data types.

Parameters

$primaryKeyDataType

An associative array mapping primary key names to their data types.

Return

self
18. setDataMap

Declaration

public function setDataMap(
    DataMap[] $dataMap
) : self
{
}

Description

Set an array of data maps for the data table.

Parameters

$dataMap

An array of data maps for the data table.

Return

self
19. addDataControl

Declaration

public function addDataControl(
    ButtonFormData $dataControl
) : self
{
}

Description

Adds a ButtonFormData object to the internal collection of data controls. This method stores the given data control for further use or processing.

Parameters

$dataControl

The ButtonFormData object to be added to the collection.

Return

self

Returns the current object instance for method chaining.

20. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

21. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

22. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

23. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

24. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

25. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

26. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ListDataTitleDto

Declaration

class ListDataTitleDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Represents the title of a column in a table row.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. field

Declaration

protected string $field;

Description

The field associated with the column title.

2. label

Declaration

protected string $label;

Description

The display value of the column title.

3. sortable

Declaration

protected bool $sortable;

Description

Indicates if the column is sortable.

4. currentSort

Declaration

protected string $currentSort;

Description

The current sort direction (ASC/DESC).

Methods

1. __construct

Declaration

public function __construct(
    string|null $field = null,
    string|null $label = null,
    bool $sortable = false,
    string|null $currentSort = null
)
{
}

Description

Constructor to initialize the column title.

Parameters

$field

The field associated with the column title.

$label

The display value of the column title.

$sortable

Indicates if the data can be sorted by this column.

$currentSort

The current sort direction (ASC/DESC).

2. getField

Declaration

public function getField() : string|null
{
}

Description

Get the field associated with the column title.

Return

string|null
3. setField

Declaration

public function setField(
    string|null $field
) : self
{
}

Description

Set the field associated with the column title.

Parameters

$field

The field associated with the column title.

Return

self

The current instance, allowing method chaining

4. getLabel

Declaration

public function getLabel() : string|null
{
}

Description

Get the display value of the column title.

Return

string|null
5. setLabel

Declaration

public function setLabel(
    string|null $label
) : self
{
}

Description

Set the display value of the column title.

Parameters

$label

The display value of the column title.

Return

self

The current instance, allowing method chaining

6. isSortable

Declaration

public function isSortable() : bool
{
}

Description

Check if the column is sortable.

Return

bool
7. setSortable

Declaration

public function setSortable(
    bool $sortable
) : self
{
}

Description

Set the sortable status of the column.

Parameters

$sortable

Indicates if the column is sortable.

Return

self

The current instance, allowing method chaining

8. getCurrentSort

Declaration

public function getCurrentSort() : string|null
{
}

Description

Get the current sort direction (ASC/DESC).

Return

string|null
9. setCurrentSort

Declaration

public function setCurrentSort(
    string|null $currentSort
) : self
{
}

Description

Set the current sort direction.

Parameters

$currentSort

The current sort direction (ASC/DESC).

Return

self

The current instance, allowing method chaining

10. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

11. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

12. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

13. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

14. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

15. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

16. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ListDto

Declaration

class ListDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Data Transfer Object (DTO) for displaying records in a table format.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. namespace

Declaration

protected string $namespace;

Description

The namespace where the module is located, such as "/", "/admin", "/supervisor", etc.

2. moduleId

Declaration

protected string $moduleId;

Description

The ID of the module associated with the data.

3. moduleName

Declaration

protected string $moduleName;

Description

The name of the module associated with the data.

4. moduleTitle

Declaration

protected string $moduleTitle;

Description

The title of the module associated with the data.

5. responseCode

Declaration

protected string $responseCode;

Description

The response code indicating the status of the request.

6. responseMessage

Declaration

protected string $responseMessage;

Description

A message providing additional information about the response.

7. data

Declaration

protected ListDataDto $data;

Description

The main data structure containing the list of items.

Methods

1. __construct

Declaration

public function __construct(
    string|null $responseCode = null,
    string|null $responseMessage = null,
    mixed $data = null
)
{
}

Description

Constructor to initialize properties.

Parameters

$responseCode

The response code.

$responseMessage

The response message.

$data

The associated data.

2. getNamespace

Declaration

public function getNamespace() : string
{
}

Description

Get the namespace where the module is located.

Return

string

The namespace.

3. setNamespace

Declaration

public function setNamespace(
    string $namespace
) : self
{
}

Description

Set the namespace where the module is located.

Parameters

$namespace

The namespace to set.

Return

self

The current instance for method chaining.

4. setPage

Declaration

public function setPage(
    PicoPageable|PicoPage|PageDto|array|null $pageable
) : self
{
}

Description

Sets the pagination details for the current object.

This method assigns a PageDto instance to the object. It accepts various types of input to initialize the pagination details:

  • A PicoPageable object, which contains the page and page size details.
  • A PicoPage object, which provides the page number and page size.
  • A PageDto object, which copies pagination information from another PageDto.
  • An array containing the page number and page size (array format: [page_number, page_size]).

    If no input is provided, the pagination is set to the default values from the constructor of PageDto (page 1, page size 10).

Parameters

$pageable

A pagination object or array providing

Return

self

Returns the current instance for method chaining.

5. addTitle

Declaration

public function addTitle(
    ListDataTitleDto $title
) : self
{
}

Description

Append a column title to the table.

Parameters

$title

The title to append.

Return

self

The current instance for method chaining.

6. addDataMap

Declaration

public function addDataMap(
    DataMap $dataMap
) : self
{
}

Description

Add a data map to the collection.

This method appends a DataMap instance to the internal data map collection. If the collection does not exist, it initializes it first. Each DataMap is stored in the data structure.

Parameters

$dataMap

The DataMap instance to add.

Return

self

The current instance for method chaining.

7. add

Declaration

public function add(
    array|stdClass|MagicObject|SetterGetter|PicoGenericObject $title
) : self
{
}

Description

Add a column title to the table.

This method accepts various types of input to create a column title, including associative arrays, stdClass objects, and instances of MagicObject, SetterGetter, or PicoGenericObject. It extracts the name and value for the title and appends it to the data structure.

Parameters

$title

The title to add, which can be:

Return

self

Returns the current instance for method chaining.

8. addPrimaryKeyName

Declaration

public function addPrimaryKeyName(
    string $primaryKeyName,
    string $primaryKeyDataType
) : self
{
}

Description

Add a primary key name and its data type to the list of primary keys.

This method initializes the primary key name and data type properties as arrays if they haven't been set, then appends the new primary key name and its corresponding data type to the lists.

Parameters

$primaryKeyName

The primary key name to add.

$primaryKeyDataType

The primary key data type to add.

Return

self

The instance of this class.

9. addData

Declaration

public function addData(
    MagicObject $data,
    MetadataDto $metadata
) : self
{
}

Description

Append a row of data to the table.

This method adds a new row of data to the internal data collection, creating a ListDataDto instance if it doesn't already exist.

Parameters

$data

The row data to append.

$metadata

The metadata associated with the row data.

Return

self

The current instance for method chaining.

10. getResponseCode

Declaration

public function getResponseCode() : string|null
{
}

Description

Get the response code indicating the status of the request.

Return

string|null
11. setResponseCode

Declaration

public function setResponseCode(
    string|null $responseCode
) : self
{
}

Description

Set the response code indicating the status of the request.

Parameters

$responseCode

The response code indicating the status of the request.

Return

self

The current instance for method chaining.

12. getResponseMessage

Declaration

public function getResponseMessage() : string|null
{
}

Description

Get a message providing additional information about the response.

Return

string|null
13. setResponseMessage

Declaration

public function setResponseMessage(
    string|null $responseMessage
) : self
{
}

Description

Set a message providing additional information about the response.

Parameters

$responseMessage

A message providing additional information about the response.

Return

self

The current instance for method chaining.

14. getData

Declaration

public function getData() : ListDataDto|null
{
}

Description

Get the main data structure containing the list of items.

Return

ListDataDto|null

The main data structure.

15. addDataControl

Declaration

public function addDataControl(
    ButtonFormData $dataControl
) : self
{
}

Description

Adds a data control to the data object. This function allows for the addition of a data control to be managed by the current object.

Parameters

$dataControl

The ButtonFormData object containing the data control to be added.

Return

self

Returns the current object instance for method chaining.

16. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

17. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

18. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

19. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

20. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

21. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

22. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ListFilterControl

Declaration

class ListFilterControl extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class ListFilterControl

Represents a filter control element for use in a list filter UI. This class holds the metadata and attributes for the filter input element, including its label, field name, and the associated HTML attributes and text content.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. label

Declaration

protected string $label;

Description

The label that will be displayed next to the filter input element.

2. field

Declaration

protected string $field;

Description

The field name that this filter corresponds to in the data model. This is typically the name of the property or column being filtered.

3. name

Declaration

protected string $name;

Description

A unique name or identifier for this filter, used to reference the filter in the UI.

4. id

Declaration

protected string $id;

Description

The unique identifier for the filter control, typically used for DOM element identification.

5. element

Declaration

protected string $element;

Description

The type of HTML input element used for the filter. This can be one of the following types:

  • "text": For text input fields.
  • "number": For numeric input fields.
  • "date": For date input fields.
  • "datetime": For date-time input fields.
  • "checkbox": For checkbox input fields.
  • "select": For drop-down select lists.
  • "button": For button elements, typically used for submitting or resetting the filter.
6. attribute

Declaration

protected array $attribute;

Description

An associative array of HTML attributes to apply to the filter element. This can include attributes like "class", "id", "style", "placeholder", etc.

7. textContent

Declaration

protected string $textContent;

Description

The text content for button elements, used to define the button's label (e.g., "Apply", "Reset").

8. selectOption

Declaration

protected SelectOptionDto $selectOption;

Description

Select option

Methods

1. getLabel

Declaration

public function getLabel() : string
{
}

Description

Gets the label of the filter input element.

Return

string

The label.

2. setLabel

Declaration

public function setLabel(
    string $label
) : self
{
}

Description

Sets the label of the filter input element.

Parameters

$label

The label to set.

Return

self

Returns the current instance for chaining.

3. getField

Declaration

public function getField() : string
{
}

Description

Gets the field name associated with the filter.

Return

string

The field name.

4. setField

Declaration

public function setField(
    string $field
) : self
{
}

Description

Sets the field name associated with the filter.

Parameters

$field

The field name to set.

Return

self

Returns the current instance for chaining.

5. getName

Declaration

public function getName() : string
{
}

Description

Gets the unique name for the filter.

Return

string

The unique name.

6. setName

Declaration

public function setName(
    string $name
) : self
{
}

Description

Sets the unique name for the filter.

Parameters

$name

The name to set.

Return

self

Returns the current instance for chaining.

7. getId

Declaration

public function getId() : string
{
}

Description

Gets the unique identifier for the filter control.

Return

string

The ID.

8. setId

Declaration

public function setId(
    string $id
) : self
{
}

Description

Sets the unique identifier for the filter control.

Parameters

$id

The ID to set.

Return

self

Returns the current instance for chaining.

9. getElement

Declaration

public function getElement() : string
{
}

Description

Gets the type of HTML element used for the filter input.

Return

string

The input element type (e.g., "text", "number").

10. setElement

Declaration

public function setElement(
    string $element
) : self
{
}

Description

Sets the type of HTML element used for the filter input.

Parameters

$element

The element type to set.

Return

self

Returns the current instance for chaining.

11. getAttribute

Declaration

public function getAttribute() : array
{
}

Description

Gets the HTML attributes associated with the filter element.

Return

array

The array of HTML attributes.

12. setAttribute

Declaration

public function setAttribute(
    array $attribute
) : self
{
}

Description

Sets the HTML attributes associated with the filter element.

Parameters

$attribute

The attributes to set.

Return

self

Returns the current instance for chaining.

13. getTextContent

Declaration

public function getTextContent() : string
{
}

Description

Gets the text content for button elements.

Return

string

The text content for button elements.

14. setTextContent

Declaration

public function setTextContent(
    string $textContent
) : self
{
}

Description

Sets the text content for button elements.

Parameters

$textContent

The text content to set.

Return

self

Returns the current instance for chaining.

15. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

16. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

17. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

18. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

19. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

20. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

21. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ListForm

Declaration

class ListForm extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class ListForm

Represents the response structure for a list-based form in a UI. This class holds metadata about the module that the form is associated with, such as the module's ID, name, and title, as well as the status of the request (via the response code and message). It also contains the main data structure (ListFormData) that holds the filter and data controls for the list.

The ListForm class is used to encapsulate all necessary information for rendering a form that interacts with a list of data. It provides details about the module's context and feedback about the request, as well as the controls and data required for filtering and displaying the list content in the UI.

Key Features:

  • Hold the metadata about the module (ID, name, and title).
  • Provide the response status and message for request feedback.
  • Contain the ListFormData structure, which manages the list's filter and data controls.
  • Allow easy access to the response details and the data form structure.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. namespace

Declaration

protected string $namespace;

Description

The namespace where the module is located, such as "/", "/admin", "/supervisor", etc.

2. moduleId

Declaration

protected string $moduleId;

Description

The ID of the module associated with the data.

3. moduleName

Declaration

protected string $moduleName;

Description

The name of the module associated with the data.

4. moduleTitle

Declaration

protected string $moduleTitle;

Description

The title of the module associated with the data.

5. responseCode

Declaration

protected string $responseCode;

Description

The response code indicating the status of the request.

6. responseMessage

Declaration

protected string $responseMessage;

Description

A message providing additional information about the response.

7. data

Declaration

protected ListFormData $data;

Description

The main data structure containing the list form.

Methods

1. getNamespace

Declaration

public function getNamespace() : string
{
}

Description

Get the namespace where the module is located.

Return

string

The namespace.

2. setNamespace

Declaration

public function setNamespace(
    string $namespace
) : self
{
}

Description

Set the namespace where the module is located.

Parameters

$namespace

The namespace to set.

Return

self

The current instance for method chaining.

3. getModuleId

Declaration

public function getModuleId() : string
{
}

Description

Get the module ID associated with the data.

Return

string

The module ID.

4. setModuleId

Declaration

public function setModuleId(
    string $moduleId
) : self
{
}

Description

Set the module ID associated with the data.

Parameters

$moduleId

The module ID to set.

Return

self

The current instance for method chaining.

5. getModuleName

Declaration

public function getModuleName() : string
{
}

Description

Get the module name associated with the data.

Return

string

The module name.

6. setModuleName

Declaration

public function setModuleName(
    string $moduleName
) : self
{
}

Description

Set the module name associated with the data.

Parameters

$moduleName

The module name to set.

Return

self

The current instance for method chaining.

7. getModuleTitle

Declaration

public function getModuleTitle() : string
{
}

Description

Get the module title associated with the data.

Return

string

The module title.

8. setModuleTitle

Declaration

public function setModuleTitle(
    string $moduleTitle
) : self
{
}

Description

Set the module title associated with the data.

Parameters

$moduleTitle

The module title to set.

Return

self

The current instance for method chaining.

9. getResponseCode

Declaration

public function getResponseCode() : string|null
{
}

Description

Get the response code indicating the status of the request.

Return

string|null

The response code.

10. setResponseCode

Declaration

public function setResponseCode(
    string|null $responseCode
) : self
{
}

Description

Set the response code indicating the status of the request.

Parameters

$responseCode

The response code to set.

Return

self

The current instance for method chaining.

11. getResponseMessage

Declaration

public function getResponseMessage() : string|null
{
}

Description

Get the response message providing additional information about the response.

Return

string|null

The response message.

12. setResponseMessage

Declaration

public function setResponseMessage(
    string|null $responseMessage
) : self
{
}

Description

Set the response message providing additional information about the response.

Parameters

$responseMessage

The response message to set.

Return

self

The current instance for method chaining.

13. getData

Declaration

public function getData() : ListFormData|null
{
}

Description

Get the main data structure containing the list form.

Return

ListFormData|null

The data structure for the form.

14. setData

Declaration

public function setData(
    ListFormData|null $data
) : self
{
}

Description

Set the main data structure containing the list form.

Parameters

$data

The data structure to set.

Return

self

The current instance for method chaining.

15. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

16. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

17. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

18. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

19. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

20. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

21. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ListFormData

Declaration

class ListFormData extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class ListFormData

Represents a form structure designed to manage and organize filtering and data controls within a list UI. This class serves as a container for filter controls (e.g., search fields, date pickers, checkboxes) and data controls (e.g., display settings, sorting, pagination). These controls enable users to interact with and manipulate the data displayed in the list.

The ListFormData class allows for easy configuration of various filters and data-related controls, such as adding, removing, or modifying filters and data controls dynamically. It also provides methods to manage the controls collectively, ensuring that the UI is adaptable and user-friendly for operations such as sorting, searching, and displaying data.

Key Features:

  • Manage a list of filter controls, each representing a specific filter UI element.
  • Manage a list of data controls, each representing a specific data-related UI element.
  • Dynamic addition of filter and data controls.
  • Chaining of method calls for adding controls and setting properties.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. filterControl

Declaration

protected ListFilterControl[] $filterControl;

Description

An array of filter control elements used for filtering data in the list. Each element is an instance of ListFilterControl, which holds metadata about the filter control (e.g., field, label, element type).

2. dataControl

Declaration

protected DataControl[] $dataControl;

Description

An array of data control elements used for managing and displaying the actual data in the list. Each element is an instance of DataControl, which holds information about the data field and its representation.

Methods

1. __construct

Declaration

public function __construct()
{
}

Description

Constructor for the ListFormData class.

Initializes the filter control and data control arrays as empty. This default constructor is useful when you want to create an object without initializing the controls right away.

2. addFilterControl

Declaration

public function addFilterControl(
    ListFilterControl $filterControl
) : self
{
}

Description

Adds a filter control to the list of filter controls.

Parameters

$filterControl

The filter control to add.

Return

self

Returns the current instance for chaining.

3. addDataControl

Declaration

public function addDataControl(
    DataControl $dataControl
) : self
{
}

Description

Adds a data control to the list of data controls.

Parameters

$dataControl

The data control to add.

Return

self

Returns the current instance for chaining.

4. getFilterControl

Declaration

public function getFilterControl() : ListFilterControl[]
{
}

Description

Gets the array of filter control elements.

Return

ListFilterControl[]

The array of filter control elements.

5. setFilterControl

Declaration

public function setFilterControl(
    ListFilterControl[] $filterControl
) : self
{
}

Description

Sets the array of filter control elements.

Parameters

$filterControl

The filter controls to set.

Return

self

Returns the current instance for chaining.

6. getDataControl

Declaration

public function getDataControl() : DataControl[]
{
}

Description

Gets the array of data control elements.

Return

DataControl[]

The array of data control elements.

7. setDataControl

Declaration

public function setDataControl(
    DataControl[] $dataControl
) : self
{
}

Description

Sets the array of data control elements.

Parameters

$dataControl

The data controls to set.

Return

self

Returns the current instance for chaining.

8. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

9. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

10. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

11. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

12. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

13. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

14. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\MetadataDetailDto

Declaration

class MetadataDetailDto extends MagicApp\AppDto\ResponseDto\MetadataDto { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Data Transfer Object (DTO) representing detailed metadata information.

The MetadataDetailDto class extends the MetadataDto class to provide specific details related to metadata associated with data operations. It includes properties that indicate the status of operations, the primary key associated with the metadata, and its active status. This class is particularly useful for scenarios requiring detailed tracking of metadata operations, such as in data approval processes, updates, or state changes.

The class provides methods for accessing and manipulating these properties while leveraging inheritance from the MetadataDto class for common metadata functionalities.

The class also extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. primaryKey

Declaration

protected array $primaryKey;

Description

Associated array key value primary key.

2. active

Declaration

protected bool $active;

Description

Indicates whether the metadata is active.

3. waitingFor

Declaration

protected int $waitingFor;

Description

Represents the status of the operation.

Possible values:

  • 1: approval for new data
  • 2: approval for updating data
  • 3: approval for activate
  • 4: approval for deactivate
  • 5: approval for delete
  • 6: approval for sort order
4. waitingForCode

Declaration

protected string $waitingForCode;

Description

Code representing the waiting status.

5. waitingForMessage

Declaration

protected string $waitingForMessage;

Description

Message associated with the waiting status.

Methods

1. __construct

Declaration

public function __construct(
    array $primaryKey,
    bool $active,
    int $waitingFor,
    string $waitingForCode,
    string $waitingForMessage
)
{
}

Description

Constructor to initialize properties of the MetadataDetailDto class.

Parameters

$primaryKey

An array representing the primary key.

$active

A boolean indicating if the metadata is active.

$waitingFor

An integer representing the operation status.

$waitingForCode

A code representing the waiting status.

$waitingForMessage

A message associated with the waiting status.

2. getPrimaryKey

Declaration

public function getPrimaryKey() : array
{
}

Description

Get the primary key associated with the metadata.

Return

array

The primary key.

3. setPrimaryKey

Declaration

public function setPrimaryKey(
    array $primaryKey
) : self
{
}

Description

Set the primary key associated with the metadata.

Parameters

$primaryKey

The primary key to set.

Return

self

The current instance for method chaining.

4. getActive

Declaration

public function getActive() : bool
{
}

Description

Get the active status of the metadata.

Return

bool

The active status.

5. setActive

Declaration

public function setActive(
    bool $active
) : self
{
}

Description

Set the active status of the metadata.

Parameters

$active

The active status to set.

Return

self

The current instance for method chaining.

6. getWaitingFor

Declaration

public function getWaitingFor() : int
{
}

Description

Get the operation status represented by the waitingFor property.

Return

int

The operation status.

7. setWaitingFor

Declaration

public function setWaitingFor(
    int $waitingFor
) : self
{
}

Description

Set the operation status represented by the waitingFor property.

Parameters

$waitingFor

The operation status to set.

Return

self

The current instance for method chaining.

8. getWaitingForCode

Declaration

public function getWaitingForCode() : string
{
}

Description

Get the code representing the waiting status.

Return

string

The waiting status code.

9. setWaitingForCode

Declaration

public function setWaitingForCode(
    string $waitingForCode
) : self
{
}

Description

Set the code representing the waiting status.

Parameters

$waitingForCode

The waiting status code to set.

Return

self

The current instance for method chaining.

10. getWaitingForMessage

Declaration

public function getWaitingForMessage() : string
{
}

Description

Get the message associated with the waiting status.

Return

string

The waiting status message.

11. setWaitingForMessage

Declaration

public function setWaitingForMessage(
    string $waitingForMessage
) : self
{
}

Description

Set the message associated with the waiting status.

Parameters

$waitingForMessage

The waiting status message to set.

Return

self

The current instance for method chaining.

12. valueOf

Declaration

public static function valueOf(
    array $primaryKeyName,
    MagicObject $data,
    string $waitingForKey,
    string $activeKey
) : MetadataDto
{
}

Description

Creates a MetadataDto instance from provided data.

This method constructs a MetadataDto by extracting values from a MagicObject based on specified keys for the primary key, waiting status, and active status.

Parameters

$primaryKeyName

An array of keys to construct the primary key.

$data

The data object from which to extract values.

$waitingForKey

The key for the waiting status in the data object.

$activeKey

The key for the active status in the data object.

Return

MetadataDto

An instance of MetadataDto populated with extracted values.

13. isActive

Declaration

public function isActive() : bool
{
}

Description

Get the active status.

Return

bool

True if active, otherwise false.

14. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

15. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

16. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

17. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

18. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

19. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

20. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\MetadataDto

Declaration

class MetadataDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Data Transfer Object (DTO) representing metadata information.

The MetadataDto class encapsulates metadata details associated with various data operations. It includes indicators for active status, a primary key to uniquely identify the metadata, and a waiting status reflecting the current state of operations. This class facilitates easy population of its properties from dynamic data sources, particularly through its static valueOf method.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. active

Declaration

protected bool $active;

Description

Indicates whether the metadata is active.

2. primaryKey

Declaration

protected array $primaryKey;

Description

Associated array key value primary key.

3. waitingFor

Declaration

protected int $waitingFor;

Description

Represents the status of the operation.

Possible values:

  • 1: approval for new data
  • 2: updating data
  • 3: activate
  • 4: deactivate
  • 5: delete
  • 6: sort order

Methods

1. valueOf

Declaration

public static function valueOf(
    array $primaryKeyName,
    MagicObject $data,
    string $waitingForKey,
    string $activeKey
) : MetadataDto
{
}

Description

Creates a MetadataDto instance from provided data.

This method constructs a MetadataDto by extracting values from a MagicObject based on specified keys for the primary key, waiting status, and active status.

Parameters

$primaryKeyName

An array of keys to construct the primary key.

$data

The data object from which to extract values.

$waitingForKey

The key for the waiting status in the data object.

$activeKey

The key for the active status in the data object.

Return

MetadataDto

An instance of MetadataDto populated with extracted values.

2. __construct

Declaration

public function __construct(
    array $primaryKey = null,
    bool $active = true,
    int $waitingFor = 0
)
{
}

Description

Constructor to initialize properties of the MetadataDto class.

Parameters

$primaryKey

An array representing the primary key.

$active

A boolean indicating if the metadata is active.

$waitingFor

An integer representing the operation status.

3. getPrimaryKey

Declaration

public function getPrimaryKey() : array
{
}

Description

Get the primary key.

Return

array

The primary key as an array.

4. setPrimaryKey

Declaration

public function setPrimaryKey(
    array $primaryKey
) : self
{
}

Description

Set the primary key.

Parameters

$primaryKey

An array representing the primary key.

Return

self

The current instance for method chaining.

5. getWaitingFor

Declaration

public function getWaitingFor() : int
{
}

Description

Get the waiting status.

Return

int

The operation status as an integer.

6. setWaitingFor

Declaration

public function setWaitingFor(
    int $waitingFor
) : self
{
}

Description

Set the waiting status.

Parameters

$waitingFor

An integer representing the new operation status.

Return

self

The current instance for method chaining.

7. isActive

Declaration

public function isActive() : bool
{
}

Description

Get the active status.

Return

bool

True if active, otherwise false.

8. setActive

Declaration

public function setActive(
    bool $active
) : self
{
}

Description

Set the active status.

Parameters

$active

A boolean indicating if the metadata should be active.

Return

self

The current instance for method chaining.

9. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

10. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

11. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

12. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

13. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

14. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

15. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\NameValueDto

Declaration

class NameValueDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Represents a key-value pair with a name and associated value.

The NameValueDto class is used to store a name and its corresponding value. This can be useful for handling pairs of data, such as in API responses, form submissions, or any context where a name and its associated value are required.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. name

Declaration

protected string $name;

Description

The name associated with the value.

2. value

Declaration

protected mixed $value;

Description

The value associated with the name.

Methods

1. __construct

Declaration

public function __construct(
    string $name,
    mixed $value
)
{
}

Description

Constructor to initialize the NameValueDto object.

Parameters

$name

The name to be associated with the value.

$value

The value to be associated with the name.

2. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

3. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

4. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

5. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

6. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

7. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

8. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\OptionDto

Declaration

class OptionDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class OptionDto

Represents an individual option within a form element such as a dropdown, select input, or any other selection component. This class stores the metadata for each option, including the text displayed to the user, the value associated with the option, whether the option is selected by default, the group to which the option belongs, and any additional HTML attributes that can be applied to the option element.

This class is particularly useful for dynamically generating form controls that require configurable options with custom attributes, such as dropdown menus, radio buttons, or checkboxes.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. text

Declaration

protected string $text;

Description

The text displayed for the option. This is typically the label that the user will see in the UI. For example, "Yes", "No", "Option 1", or "Select Country".

2. value

Declaration

protected string $value;

Description

The value associated with the option. This value is typically sent as part of the form data when the user selects this option. It could represent an ID, code, or any other identifier related to the option.

3. group

Declaration

protected string $group;

Description

The group name to which the option belongs. This could be used to categorize or group options. For example, grouping options for a specific category like 'Countries' or 'Product Types'.

4. selected

Declaration

protected bool $selected;

Description

Indicates whether the option is selected by default. If set to true, the option will be pre-selected when the form is rendered. If set to false, the option will not be selected by default.

5. attribute

Declaration

protected array $attribute;

Description

An associative array of HTML attributes for the option element. This allows for customization of the appearance or behavior of the option in the rendered HTML, such as adding a disabled or data-* attribute.

Methods

1. __construct

Declaration

public function __construct(
    string $text = '',
    string $value = '',
    bool $selected = false,
    string|null $group = null,
    array $attribute = array ( )
)
{
}

Description

Constructor for the OptionDto class.

Initializes the text, value, selected, group, and attribute properties. By default, the selected flag is set to false, and attribute is an empty array.

Parameters

$text

The text to display for the option (e.g., "Yes", "No").

$value

The value to associate with the option (e.g., "1", "0").

$selected

Whether the option is selected by default. Defaults to false.

$group

The group name to which this option belongs (e.g., 'Countries', 'Payment Methods'). Defaults to null.

$attribute

Additional HTML attributes for the option element (e.g., disabled, data-*).

2. getText

Declaration

public function getText() : string
{
}

Description

Gets the text to display for the option.

Return

string

The option text.

3. setText

Declaration

public function setText(
    string $text
) : self
{
}

Description

Sets the text to display for the option.

Parameters

$text

The option text to set.

Return

self

Returns the current instance for chaining.

4. getValue

Declaration

public function getValue() : string
{
}

Description

Gets the value associated with the option.

Return

string

The option value.

5. setValue

Declaration

public function setValue(
    string $value
) : self
{
}

Description

Sets the value associated with the option.

Parameters

$value

The option value to set.

Return

self

Returns the current instance for chaining.

6. isSelected

Declaration

public function isSelected() : bool
{
}

Description

Gets whether the option is selected by default.

Return

bool

true if the option is selected by default, otherwise false.

7. setSelected

Declaration

public function setSelected(
    bool $selected
) : self
{
}

Description

Sets whether the option should be selected by default.

Parameters

$selected

Whether the option is selected by default.

Return

self

Returns the current instance for chaining.

8. getGroup

Declaration

public function getGroup() : string
{
}

Description

Gets the group to which this option belongs.

Return

string

The group name of the option.

9. setGroup

Declaration

public function setGroup(
    string $group
) : self
{
}

Description

Sets the group to which this option belongs.

Parameters

$group

The group name to set.

Return

self

Returns the current instance for chaining.

10. getAttribute

Declaration

public function getAttribute() : array
{
}

Description

Gets the array of HTML attributes for the option element.

Return

array

The option's HTML attributes (e.g., disabled, data-*).

11. setAttribute

Declaration

public function setAttribute(
    array $attribute
) : self
{
}

Description

Sets the array of HTML attributes for the option element.

Parameters

$attribute

The attributes to set.

Return

self

Returns the current instance for chaining.

12. addAttribute

Declaration

public function addAttribute(
    array $attribute
) : self
{
}

Description

Adds an individual HTML attribute to the option element.

Parameters

$attribute

An associative array of attribute key-value pairs to add.

Return

self

Returns the current instance for chaining.

13. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

14. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

15. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

16. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

17. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

18. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

19. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\PageDto

Declaration

class PageDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class PageDto

Represents an object that handles pagination details, including the page number, page size, and the data offset. This class is useful for managing pagination in collections of data. It can be initialized with various pagination-related objects such as PicoPageable, PicoPage, or another PageDto, or with an array containing the page number and page size.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. pageNumber

Declaration

protected int $pageNumber;

Description

The current page number, start from 1

2. pageSize

Declaration

protected int $pageSize;

Description

The page size, i.e., the number of items displayed per page

3. dataOffset

Declaration

protected int $dataOffset;

Description

The data offset, which is used to calculate the starting position of data on the current page.

Methods

1. __construct

Declaration

public function __construct(
    PicoPageable|PicoPage|PageDto|array|null $page = null
)
{
}

Description

Constructor for the PageDto class.

This constructor initializes the pagination details (page number, page size, and data offset). It can accept various types of input, including:

  • PicoPageable object: A paginated object that provides the current page and page size.
  • PicoPage object: A simpler object that holds pagination information.
  • PageDto object: An existing PageDto to copy pagination data from.
  • array: An array where the first element is the page number and the second element is the page size.

    If no parameter is provided, the pagination defaults to page 1 with a page size of 10.

Parameters

$page

An optional object or array that provides pagination

2. getPageNumber

Declaration

public function getPageNumber() : int
{
}

Description

Gets the current page number.

Return

int

The current page number.

3. setPageNumber

Declaration

public function setPageNumber(
    int $pageNumber
) : self
{
}

Description

Sets the current page number.

Parameters

$pageNumber

The page number to set.

Return

self

Returns the current instance for chaining.

4. getPageSize

Declaration

public function getPageSize() : int
{
}

Description

Gets the page size (the number of items per page).

Return

int

The page size.

5. setPageSize

Declaration

public function setPageSize(
    int $pageSize
) : self
{
}

Description

Sets the page size.

Parameters

$pageSize

The page size to set.

Return

self

Returns the current instance for chaining.

6. getDataOffset

Declaration

public function getDataOffset() : int
{
}

Description

Gets the data offset (the starting position of data on the current page).

Return

int

The data offset.

7. setDataOffset

Declaration

public function setDataOffset(
    int $dataOffset
) : self
{
}

Description

Sets the data offset.

Parameters

$dataOffset

The data offset to set.

Return

self

Returns the current instance for chaining.

8. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

9. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

10. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

11. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

12. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

13. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

14. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\PrimaryKeyValueDto

Declaration

class PrimaryKeyValueDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Represents a key-value pair with a name and associated value.

The PrimaryKeyValueDto class is used to store a name and its corresponding value. This can be useful for handling pairs of data, such as in API responses, form submissions, or any context where a name and its associated value are required.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. name

Declaration

protected string $name;

Description

The name associated with the value.

2. value

Declaration

protected mixed $value;

Description

The value associated with the name.

Methods

1. __construct

Declaration

public function __construct(
    string $name,
    mixed $value
)
{
}

Description

Constructor to initialize the PrimaryKeyValueDto object.

Parameters

$name

The name to be associated with the value.

$value

The value to be associated with the name.

2. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

3. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

4. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

5. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

6. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

7. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

8. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ResponseCode

Declaration

class ResponseCode extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class ResponseCode

This class represents the structure for a response code and its associated message. It encapsulates the response code that indicates the status of a request, along with a message that provides additional context about the response.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. responseCode

Declaration

protected string $responseCode;

Description

The response code indicating the status of the request.

2. responseMessage

Declaration

protected string $responseMessage;

Description

A message providing additional information about the response.

Methods

1. __construct

Declaration

public function __construct(
    string $responseCode = '',
    string $responseMessage = ''
)
{
}

Description

Constructor for initializing a ResponseCode instance.

Parameters

$responseCode

The response code.

$responseMessage

The response message.

2. getResponseCode

Declaration

public function getResponseCode() : string
{
}

Description

Get the response code.

Return

string

The response code.

3. setResponseCode

Declaration

public function setResponseCode(
    string $responseCode
) : self
{
}

Description

Set the response code.

Parameters

$responseCode

The response code.

Return

self

The current instance for method chaining.

4. getResponseMessage

Declaration

public function getResponseMessage() : string
{
}

Description

Get the response message.

Return

string

The response message.

5. setResponseMessage

Declaration

public function setResponseMessage(
    string $responseMessage
) : self
{
}

Description

Set the response message.

Parameters

$responseMessage

The response message.

Return

self

The current instance for method chaining.

6. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

7. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

8. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

9. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

10. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

11. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

12. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ResponseDto

Declaration

class ResponseDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class ResponseDto

Represents a data transfer object for API responses. This class holds the response code, message, and associated data.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. responseCode

Declaration

protected string $responseCode;

Description

The response code indicating the status of the request.

2. responseMessage

Declaration

protected string $responseMessage;

Description

A message providing additional information about the response.

3. data

Declaration

protected mixed $data;

Description

The data associated with the response.

Methods

1. __construct

Declaration

public function __construct(
    string|null $responseCode = null,
    string|null $responseMessage = null,
    mixed $data = null
)
{
}

Description

Constructor to initialize properties.

Parameters

$responseCode

The response code.

$responseMessage

The response message.

$data

The associated data.

2. setMetadata

Declaration

public function setMetadata(
    MetadataDto $metadata
) : self
{
}

Description

Set the metadata for the data object and return the current instance for method chaining.

This method delegates the setting of metadata to the data object's setMetadata method.

Parameters

$metadata

The metadata to associate with the data object.

Return

self

The current instance for method chaining. The current instance for method chaining.

3. getResponseCode

Declaration

public function getResponseCode() : string|null
{
}

Description

Get the response code.

Return

string|null
4. setResponseCode

Declaration

public function setResponseCode(
    string|null $responseCode
) : self
{
}

Description

Set the response code.

Parameters

$responseCode

The response code to set.

Return

self

The current instance for method chaining.

5. getResponseMessage

Declaration

public function getResponseMessage() : string|null
{
}

Description

Get the response message.

Return

string|null
6. setResponseMessage

Declaration

public function setResponseMessage(
    string|null $responseMessage
) : self
{
}

Description

Set the response message.

Parameters

$responseMessage

The response message to set.

Return

self

The current instance for method chaining.

7. getData

Declaration

public function getData() : mixed
{
}

Description

Get the associated data.

Return

mixed
8. setData

Declaration

public function setData(
    mixed $data
) : self
{
}

Description

Set the associated data.

Parameters

$data

The data to set.

Return

self

The current instance for method chaining.

9. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

10. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

11. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

12. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

13. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

14. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

15. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\RowDto

Declaration

class RowDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Data Transfer Object (DTO) representing a row of data with associated metadata.

The RowDto class encapsulates a single row of data within a dataset, along with its corresponding metadata. This class is designed to hold both the data object, which can be dynamically structured through the MagicObject class, and the metadata that provides additional context about the row's status and attributes.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. data

Declaration

protected MagicObject $data;

Description

Data associated with the row.

2. metadata

Declaration

protected MetadataDto $metadata;

Description

Metadata associated with the row.

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $data,
    MetadataDto $metadata
)
{
}

Description

Constructor to initialize properties of the RowDto class.

Parameters

$data

The data object for the row.

$metadata

The metadata associated with the data object.

2. getData

Declaration

public function getData() : MagicObject
{
}

Description

Get the data object.

Return

MagicObject

The data object associated with the row.

3. setData

Declaration

public function setData(
    MagicObject $data
) : self
{
}

Description

Set the data object and return the current instance for method chaining.

Parameters

$data

The new data object.

Return

self

The current instance for method chaining.

4. getMetadata

Declaration

public function getMetadata() : MetadataDto
{
}

Description

Get the metadata object.

Return

MetadataDto

The metadata object associated with the row.

5. setMetadata

Declaration

public function setMetadata(
    MetadataDto $metadata
) : self
{
}

Description

Set the metadata object and return the current instance for method chaining.

Parameters

$metadata

The new metadata object.

Return

self

The current instance for method chaining.

6. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

7. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

8. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

9. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

10. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

11. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

12. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\SelectOptionDto

Declaration

class SelectOptionDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class SelectOptionDto

Represents an individual option within a select input element in a form. This class holds metadata related to a selection option, including the source from which the option is derived, its group (if it's part of a grouped set of options), the field it corresponds to in the data model, and the actual OptionDto that contains the option's display text, value, and other properties.

The SelectOptionDto is commonly used to handle structured options that come from a dynamic data source, such as an API or database, allowing for proper grouping, categorization, and representation of the option in a form element.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. source

Declaration

protected string $source;

Description

The source from which the option is derived. This could represent a data source, such as an API or a database query, that provides the available options for selection.

Examples of source values could be "API", "Database", or a specific data path.

2. namespace

Declaration

protected string $namespace;

Description

The namespace where the module is located, such as "/", "/admin", "/supervisor", etc.

3. field

Declaration

protected string $field;

Description

The field that this option corresponds to. This could be the name of the property or column in the underlying data model that the option represents.

For instance, if the option represents a country, the field could be "country_id".

4. option

Declaration

protected OptionDto $option;

Description

The OptionDto object that contains the actual option's text, value, and attributes. This defines a single selection option, which typically includes properties like the option's display text and value.

Methods

1. __construct

Declaration

public function __construct(
    string $source = '',
    string $namespace = '',
    string $field = '',
    OptionDto $option = null
)
{
}

Description

Constructor for the SelectOptionDto class.

Initializes the source, group, field, and option properties. If no OptionDto is provided, an empty OptionDto will be created to initialize the option.

Parameters

$source

The source from which the option is derived (e.g., API, Database).

$namespace

The namespace where the module is located, such as "/", "/admin", "/supervisor", etc.

$field

The field associated with this option (e.g., country_id, product_id).

$option

An instance of OptionDto that defines the option's metadata.

2. getSource

Declaration

public function getSource() : string
{
}

Description

Gets the source from which the option is derived.

Return

string

The source of the option (e.g., API, Database).

3. setSource

Declaration

public function setSource(
    string $source
) : self
{
}

Description

Sets the source from which the option is derived.

Parameters

$source

The source to set (e.g., API, Database).

Return

self

Returns the current instance for chaining.

4. getNamespace

Declaration

public function getNamespace() : string
{
}

Description

Get the namespace where the module is located.

Return

string

The namespace.

5. setNamespace

Declaration

public function setNamespace(
    string $namespace
) : self
{
}

Description

Set the namespace where the module is located.

Parameters

$namespace

The namespace to set.

Return

self

The current instance for method chaining.

6. getField

Declaration

public function getField() : string
{
}

Description

Gets the field that this option corresponds to.

Return

string

The field name of the option (e.g., country_id, product_id).

7. setField

Declaration

public function setField(
    string $field
) : self
{
}

Description

Sets the field that this option corresponds to.

Parameters

$field

The field name to set (e.g., country_id, product_id).

Return

self

Returns the current instance for chaining.

8. getOption

Declaration

public function getOption() : OptionDto
{
}

Description

Gets the OptionDto object that defines the option's metadata (text, value, etc.).

Return

OptionDto

The option's metadata (e.g., text, value, selected state).

9. setOption

Declaration

public function setOption(
    OptionDto $option
) : self
{
}

Description

Sets the OptionDto object that defines the option's metadata.

Parameters

$option

The option metadata to set.

Return

self

Returns the current instance for chaining.

10. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

11. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

12. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

13. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

14. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

15. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

16. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\StandardClass

Declaration

class StandardClass extends stdClass { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

StandardClass extends the base stdClass and customizes the __toString method. This class provides a custom string representation of the object, converting it into a JSON format that can be optionally pretty-printed depending on the prettify property.

Properties

1. prettify

Declaration

private $prettify = false;

Description

@var bool Determines if the JSON output should be pretty-printed.

Methods

1. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the object to a string in JSON format.

This method overrides the default __toString method to return a JSON representation of the object. If the prettify property is set to true, the JSON will be pretty-printed. Otherwise, it will be compact.

Return

string

The JSON-encoded string representation of the object.

2. setPrettify

Declaration

public function setPrettify(
    bool $prettify
) : self
{
}

Description

Set the value of the prettify property.

This method controls whether the JSON output will be formatted with pretty-printing or be in compact form.

Parameters

$prettify

Set to true to enable pretty-printing, false to disable.

Return

self

Returns the current object instance for method chaining.

MagicApp\AppDto\ResponseDto\ToString

Declaration

class ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Base class that provides a __toString method for derived classes.

This class allows converting objects into a string representation (typically JSON), with customizable property naming strategies (e.g., snake_case, camelCase).

It is designed to be extended by other Data Transfer Object (DTO) classes to provide consistent string output across the application.

Features:

  • Retrieves properties of the current instance, applying specified naming strategies (e.g., snake_case, camelCase).
  • Correctly formats nested objects and arrays according to the naming conventions.
  • Uses reflection to read class annotations for dynamic property naming strategy.
  • Implements the __toString method to output a JSON representation of the object.

    Supported Naming Strategies:

  • SNAKE_CASE: Converts property names to snake_case (e.g., myProperty becomes my_property).
  • KEBAB_CASE: Converts property names to kebab-case (e.g., myProperty becomes my-property).
  • TITLE_CASE: Converts property names to Title Case (e.g., myProperty becomes My Property).
  • CAMEL_CASE: The default naming convention (e.g., my_property becomes myProperty).
  • PASCAL_CASE: Converts property names to PascalCase (e.g., myProperty becomes MyProperty).
  • CONSTANT_CASE: Converts property names to CONSTANT_CASE (e.g., myProperty becomes MY_PROPERTY).
  • FLAT_CASE: Converts property names to lowercase without any delimiters (e.g., myProperty becomes myproperty).
  • DOT_NOTATION: Converts property names to dot notation (e.g., myProperty becomes my.property).
  • TRAIN_CASE: Converts property names to TRAIN-CASE (e.g., myProperty becomes MY-PROPERTY).

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. propertySet

Declaration

private bool $propertySet;

Description

Check if $propertyNamingStrategy and $prettify are set

2. propertyNamingStrategy

Declaration

private string $propertyNamingStrategy;

Description

Undocumented variable

3. prettify

Declaration

private bool $prettify;

Description

Undocumented variable

Methods

1. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

2. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

3. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

4. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

5. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

6. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

7. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\UpdateForm

Declaration

class UpdateForm extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class UpdateForm

Represents the response structure for a list-based form in a UI. This class holds metadata about the module that the form is associated with, such as the module's ID, name, and title, as well as the status of the request (via the response code and message). It also contains the main data structure (UpdateFormData) that holds the filter and data controls for the list.

The UpdateForm class is used to encapsulate all necessary information for rendering a form that interacts with a list of data. It provides details about the module's context and feedback about the request, as well as the controls and data required for filtering and displaying the list content in the UI.

Key Features:

  • Hold the metadata about the module (ID, name, and title).
  • Provide the response status and message for request feedback.
  • Contain the UpdateFormData structure, which manages the list's filter and data controls.
  • Allow easy access to the response details and the data form structure.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. namespace

Declaration

protected string $namespace;

Description

The namespace where the module is located, such as "/", "/admin", "/supervisor", etc.

2. moduleId

Declaration

protected string $moduleId;

Description

The ID of the module associated with the data.

3. moduleName

Declaration

protected string $moduleName;

Description

The name of the module associated with the data.

4. moduleTitle

Declaration

protected string $moduleTitle;

Description

The title of the module associated with the data.

5. responseCode

Declaration

protected string $responseCode;

Description

The response code indicating the status of the request.

6. responseMessage

Declaration

protected string $responseMessage;

Description

A message providing additional information about the response.

7. data

Declaration

protected UpdateFormData $data;

Description

The main data structure containing the list form.

Methods

1. getNamespace

Declaration

public function getNamespace() : string
{
}

Description

Get the namespace where the module is located.

Return

string

The namespace.

2. setNamespace

Declaration

public function setNamespace(
    string $namespace
) : self
{
}

Description

Set the namespace where the module is located.

Parameters

$namespace

The namespace to set.

Return

self

The current instance for method chaining.

3. getModuleId

Declaration

public function getModuleId() : string
{
}

Description

Get the module ID associated with the data.

Return

string

The module ID.

4. setModuleId

Declaration

public function setModuleId(
    string $moduleId
) : self
{
}

Description

Set the module ID associated with the data.

Parameters

$moduleId

The module ID to set.

Return

self

The current instance for method chaining.

5. getModuleName

Declaration

public function getModuleName() : string
{
}

Description

Get the module name associated with the data.

Return

string

The module name.

6. setModuleName

Declaration

public function setModuleName(
    string $moduleName
) : self
{
}

Description

Set the module name associated with the data.

Parameters

$moduleName

The module name to set.

Return

self

The current instance for method chaining.

7. getModuleTitle

Declaration

public function getModuleTitle() : string
{
}

Description

Get the module title associated with the data.

Return

string

The module title.

8. setModuleTitle

Declaration

public function setModuleTitle(
    string $moduleTitle
) : self
{
}

Description

Set the module title associated with the data.

Parameters

$moduleTitle

The module title to set.

Return

self

The current instance for method chaining.

9. getResponseCode

Declaration

public function getResponseCode() : string|null
{
}

Description

Get the response code indicating the status of the request.

Return

string|null

The response code.

10. setResponseCode

Declaration

public function setResponseCode(
    string|null $responseCode
) : self
{
}

Description

Set the response code indicating the status of the request.

Parameters

$responseCode

The response code to set.

Return

self

The current instance for method chaining.

11. getResponseMessage

Declaration

public function getResponseMessage() : string|null
{
}

Description

Get the response message providing additional information about the response.

Return

string|null

The response message.

12. setResponseMessage

Declaration

public function setResponseMessage(
    string|null $responseMessage
) : self
{
}

Description

Set the response message providing additional information about the response.

Parameters

$responseMessage

The response message to set.

Return

self

The current instance for method chaining.

13. getData

Declaration

public function getData() : UpdateFormData|null
{
}

Description

Get the main data structure containing the list form.

Return

UpdateFormData|null

The data structure for the form.

14. setData

Declaration

public function setData(
    UpdateFormData|null $data
) : self
{
}

Description

Set the main data structure containing the list form.

Parameters

$data

The data structure to set.

Return

self

The current instance for method chaining.

15. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

16. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

17. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

18. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

19. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

20. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

21. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\UpdateFormData

Declaration

class UpdateFormData extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class UpdateFormData

Represents the data structure for updating form filters or input fields in the UI. This class defines the configuration for a form element intended to update data in the backend. It includes properties related to form inputs, such as the columns or input fields that are displayed in the form for the user to interact with.

In this class, the column property holds an array of InputFormData objects, which represent the individual fields in the update form.

Properties:

  • column: An array of InputFormData objects, each representing a column or input field in the form.
  • button: An array of ButtonFormData objects, representing buttons in the form (optional).

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. column

Declaration

protected InputFormData[] Array of `InputFormData` objects. $column;

Description

The columns or input fields associated with the update form. This property holds an array of InputFormData objects, each representing a column or input field used in updating data.

2. button

Declaration

protected ButtonFormData[] Array of `ButtonFormData` objects. $button;

Description

The buttons associated with the update form. This property holds an array of ButtonFormData objects, each representing a button within the form. Buttons are typically used for submitting the form or triggering specific actions.

Methods

1. __construct

Declaration

public function __construct()
{
}

Description

UpdateFormData constructor.

Initializes the column property as an empty array. Initializes the button property as an empty array.

2. getColumn

Declaration

public function getColumn() : InputFormData[]
{
}

Description

Gets the array of InputFormData objects representing the columns or input fields.

This method retrieves the form columns (input fields) that the user will interact with.

Return

InputFormData[]

The array of InputFormData objects.

3. setColumn

Declaration

public function setColumn(
    InputFormData[] $column
) : self
{
}

Description

Sets the array of InputFormData objects representing the columns or input fields.

This method sets the column property to a new array of InputFormData objects. It allows the entire array of columns to be updated at once.

Parameters

$column

The array of InputFormData objects to set.

Return

self

Returns the current instance for method chaining.

4. addColumn

Declaration

public function addColumn(
    InputFormData $inputFormData
) : self
{
}

Description

Adds a single InputFormData object to the column array.

This method appends a single InputFormData object to the column property, which is an array.

Parameters

$inputFormData

The InputFormData object to add to the column array.

Return

self

Returns the current instance for method chaining.

5. getButton

Declaration

public function getButton() : ButtonFormData[]
{
}

Description

Gets the array of ButtonFormData objects associated with the form.

This method retrieves the array of ButtonFormData objects that represent the buttons in the form, such as "Submit" or "Reset" buttons.

Return

ButtonFormData[]

The array of ButtonFormData objects.

6. setButton

Declaration

public function setButton(
    ButtonFormData[] $button
) : self
{
}

Description

Sets the array of ButtonFormData objects representing the buttons in the form.

This method sets the button property to an array of ButtonFormData objects. It allows you to update the buttons in the form.

Parameters

$button

The array of ButtonFormData objects to set.

Return

self

Returns the current instance for method chaining.

7. addButton

Declaration

public function addButton(
    ButtonFormData $buttonFormData
) : self
{
}

Description

Adds a single ButtonFormData object to the button array.

This method appends a single ButtonFormData object to the button property.

Parameters

$buttonFormData

The ButtonFormData object to add to the button array.

Return

self

Returns the current instance for method chaining.

8. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

9. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

10. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

11. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

12. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

13. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

14. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\AppDto\ResponseDto\ValueDto

Declaration

class ValueDto extends MagicApp\AppDto\ResponseDto\ToString { }

Package

MagicApp\AppDto\ResponseDto

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Data Transfer Object (DTO) representing a value with display and raw data.

The ValueDto class is designed to encapsulate a piece of data that consists of a displayable representation and its underlying raw value. This class is particularly useful in scenarios where data needs to be presented in a user-friendly format while retaining access to the original, unprocessed data.

The class extends the ToString base class, enabling string representation based on the specified property naming strategy.

Constants

const SNAKE_CASE = 'SNAKE_CASE';
const KEBAB_CASE = 'KEBAB_CASE';
const TITLE_CASE = 'TITLE_CASE';
const CAMEL_CASE = 'CAMEL_CASE';
const PASCAL_CASE = 'PASCAL_CASE';
const CONSTANT_CASE = 'CONSTANT_CASE';
const FLAT_CASE = 'FLAT_CASE';
const DOT_NOTATION = 'DOT_NOTATION';
const TRAIN_CASE = 'TRAIN_CASE';
const JSON = 'JSON';
const VALUE_TRUE = 'true';
const REGEX_NAMING_STRATEGY = '/([a-z])([A-Z])/';

Properties

1. display

Declaration

protected mixed $display;

Description

Data to be displayed.

2. raw

Declaration

protected mixed $raw;

Description

Raw data.

Methods

1. __construct

Declaration

public function __construct(
    mixed $display = null,
    mixed|null $raw = null
)
{
}

Description

Constructor to initialize properties of the ValueDto class.

If the raw data is not provided, it defaults to the display data.

Parameters

$display

The data to be displayed.

$raw

The raw data.

2. getDisplay

Declaration

public function getDisplay() : mixed
{
}

Description

Get the data to be displayed.

Return

mixed

The data to be displayed.

3. setDisplay

Declaration

public function setDisplay(
    mixed $display
) : self
{
}

Description

Set the data to be displayed and return the current instance for method chaining.

Parameters

$display

The data to set for display.

Return

self

The current instance for method chaining.

4. getRaw

Declaration

public function getRaw() : mixed
{
}

Description

Get the raw data.

Return

mixed

The raw data.

5. setRaw

Declaration

public function setRaw(
    mixed $raw
) : self
{
}

Description

Set the raw data and return the current instance for method chaining.

Parameters

$raw

The raw data to set.

Return

self

The current instance for method chaining.

6. propertyValue

Declaration

public function propertyValue(
    string|null $namingStrategy = null,
    bool $prettify = false
) : StandardClass
{
}

Description

Retrieves and formats the properties of the current instance according to the specified naming strategy.

This method extracts all properties of the current object, applies the given naming strategy (such as camelCase or snake_case), and processes nested objects or arrays recursively. The result is returned as an instance of StandardClass, with private properties excluded from the output.

If no naming strategy is provided, the strategy is derived from class annotations, if available, or defaults to the naming convention of the class.

The method also supports pretty-printing of the output if the prettify flag is set to true. Nested objects and arrays will have their properties or keys recursively formatted with the specified naming strategy.

Private properties from the current class are excluded from the formatted result, but public and protected properties will be included, even if they are inherited.

Parameters

$namingStrategy

The naming strategy to apply when formatting property names.

$prettify

Whether to pretty-print the resulting JSON output. Default is false.

Return

StandardClass

An object containing the formatted property values with the specified naming strategy.

7. processArray

Declaration

protected function processArray(
    array $value,
    string $namingStrategy
) : array
{
}

Description

Process an array of values, applying the naming strategy to each key and value.

Parameters

$value

The array to process.

$namingStrategy

The naming strategy to apply.

Return

array

The processed array with formatted keys and values.

8. convertPropertyName

Declaration

protected function convertPropertyName(
    string $name,
    string $format
) : string
{
}

Description

Converts the property name to the desired format based on the specified naming convention.

The supported naming conventions are:

  • SNAKE_CASE
  • KEBAB_CASE
  • TITLE_CASE
  • CAMEL_CASE (default)
  • PASCAL_CASE
  • CONSTANT_CASE
  • FLAT_CASE
  • DOT_NOTATION
  • TRAIN_CASE

Parameters

$name

The original property name.

$format

The desired naming format.

Return

string

The converted property name.

9. parseAnnotation

Declaration

private function parseAnnotation(
    string $className
) : self
{
}

Description

Parses the annotations in the class doc comment to retrieve the property-naming-strategy and prettify values and sets them to the current instance.

This method uses the PicoAnnotationParser to extract and parse the @JSON annotation from the class doc comment. It retrieves the property-naming-strategy and prettify values and stores them in the instance for later use.

Parameters

$className

The fully qualified name of the class to inspect.

Return

self

Returns the current instance for method chaining.

10. getPropertyNamingStrategy

Declaration

public function getPropertyNamingStrategy(
    string $className
) : string|null
{
}

Description

Retrieves the property-naming-strategy value from the class annotations.

This method checks if the property-naming-strategy annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the property-naming-strategy value, which determines how property names should be formatted (e.g., camelCase, snake_case).

Parameters

$className

The fully qualified name of the class to inspect.

Return

string|null

The value of the property-naming-strategy annotation or null if not found.

11. getPrettify

Declaration

public function getPrettify(
    string $className
) : bool
{
}

Description

Retrieves the prettify value from the class annotations.

This method checks if the prettify annotation has been parsed already. If not, it calls parseAnnotation() to parse and set the required values. Once set, it returns the prettify value, which determines if the output should be formatted as pretty (i.e., indented) JSON.

Parameters

$className

The fully qualified name of the class to inspect.

Return

bool

Returns true if the prettify annotation is set to "true", false otherwise.

12. __toString

Declaration

public function __toString() : string
{
}

Description

Converts the instance to a JSON string representation based on class annotations.

This method uses the propertyValue() method to format the properties of the object and returns a JSON string. If the prettify annotation is set to true, the output will be prettified (formatted with indentation).

Return

string

A JSON string representation of the instance.

MagicApp\Config\ConfigEncrypter

Declaration

class ConfigEncrypter { }

Description

Class ConfigEncrypter

This class is responsible for encrypting and decrypting configuration files. It utilizes secret management for various configuration components such as database, mailer, session, and Redis. The class requires a callback function for password handling during the encryption and decryption processes.

Properties

1. callbaskPassword

Declaration

private callable $callbaskPassword;

Description

Callback password

Methods

1. __construct

Declaration

public function __construct(
    callable $callbaskPassword
)
{
}

Description

Constructor

Initializes the ConfigEncrypter with a callback function for password handling.

Parameters

$callbaskPassword

Callback function to retrieve password.

Throws

InvalidParameterException

if the callback is not callable.

2. encryptConfig

Declaration

public function encryptConfig(
    string $inputPath,
    string $outputPath
) : boolean
{
}

Description

Encrypt configuration

Loads a configuration from a YAML file, encrypts its sensitive components, and writes the encrypted configuration to a specified output path.

Parameters

$inputPath

Input configuration path.

$outputPath

Output configuration path.

Return

boolean

True on success, false on failure.

3. decryptConfig

Declaration

public function decryptConfig(
    string $inputPath,
    string $outputPath
) : boolean
{
}

Description

Decrypt configuration

Loads an encrypted configuration from a YAML file, decrypts its components, and writes the decrypted configuration to a specified output path.

Parameters

$inputPath

Input configuration path.

$outputPath

Output configuration path.

Return

boolean

True on success, false on failure.

MagicApp\Config\SecretDatabaseReader

Declaration

class SecretDatabaseReader extends MagicObject\SecretObject { }

Package

MagicApp\Config

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class SecretDatabaseReader

This class is responsible for reading and decrypting the configuration details for a database connection. The class extends the SecretObject class and retrieves sensitive database configuration values (such as database driver, file, host, port, username, password, etc.) from an encrypted source.

The properties of this class represent various database connection settings, and are marked with the @DecryptOut annotation to signify that these values should be decrypted when accessed. This class is designed to be used for managing sensitive database connection details securely.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. driver

Declaration

protected $driver;

Description

Database server driver

2. databaseFilePath

Declaration

protected $databaseFilePath;

Description

Database file path (for SQLite)

3. host

Declaration

protected $host;

Description

Database server host

4. port

Declaration

protected $port;

Description

Database port

5. username

Declaration

protected $username;

Description

Database username

6. password

Declaration

protected $password;

Description

Database user password

7. databaseName

Declaration

protected $databaseName;

Description

Database name

8. databseSchema

Declaration

protected $databseSchema;

Description

Database schema

9. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

10. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\Config\SecretDatabaseWriter

Declaration

class SecretDatabaseWriter extends MagicObject\SecretObject { }

Package

MagicApp\Config

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class SecretDatabaseWriter

This class is responsible for encrypting and writing the configuration details for a database connection. The class extends the SecretObject class and manages sensitive database configuration values (such as database driver, file, host, port, username, password, etc.) before they are stored or transmitted in an encrypted format.

The properties of this class represent various database connection settings, and are marked with the @EncryptIn annotation to signify that these values should be encrypted before being saved or used. This class is intended for securely managing database connection details, ensuring that sensitive data is not stored in plaintext.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. driver

Declaration

protected $driver;

Description

Database server driver

2. databaseFilePath

Declaration

protected $databaseFilePath;

Description

Database file path (for SQLite)

3. host

Declaration

protected $host;

Description

Database server host

4. port

Declaration

protected $port;

Description

Database port

5. username

Declaration

protected $username;

Description

Database username

6. password

Declaration

protected $password;

Description

Database user password

7. databaseName

Declaration

protected $databaseName;

Description

Database name

8. databseSchema

Declaration

protected $databseSchema;

Description

Database schema

9. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

10. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\Config\SecretMailerReader

Declaration

class SecretMailerReader extends MagicObject\SecretObject { }

Package

MagicApp\Config

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class SecretMailerReader

This class is responsible for reading and decrypting sensitive email configuration details such as SMTP server settings, sender's credentials, and other related configurations. The class extends the SecretObject class, which handles the decryption of sensitive data.

The properties in this class are used to store the necessary configuration values for sending emails via an SMTP server. These properties are marked with the @DecryptOut annotation to indicate that the values should be decrypted when read. This class is intended to securely manage mailer credentials and configuration settings.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. host

Declaration

protected $host;

Description

SMTP host

2. port

Declaration

protected $port;

Description

SMTP port

3. username

Declaration

protected $username;

Description

Sender username

4. password

Declaration

protected $password;

Description

Sender password

5. senderAddress

Declaration

protected $senderAddress;

Description

Sender mail address

6. senderName

Declaration

protected $senderName;

Description

Sender name

7. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

8. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\Config\SecretMailerWriter

Declaration

class SecretMailerWriter extends MagicObject\SecretObject { }

Package

MagicApp\Config

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class SecretMailerWriter

This class is responsible for encrypting and storing sensitive email configuration details such as SMTP server settings, sender's credentials, and other related configurations. The class extends the SecretObject class, which handles the encryption of sensitive data before storing them.

The properties in this class store the necessary configuration values for sending emails via an SMTP server. These properties are marked with the @EncryptIn annotation, which indicates that the values should be encrypted before being stored. This class is intended to securely manage and encrypt mailer credentials and configuration settings.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. host

Declaration

protected $host;

Description

SMTP host

2. port

Declaration

protected $port;

Description

SMTP port

3. username

Declaration

protected $username;

Description

Sender username

4. password

Declaration

protected $password;

Description

Sender password

5. senderAddress

Declaration

protected $senderAddress;

Description

Sender mail address

6. senderName

Declaration

protected $senderName;

Description

Sender name

7. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

8. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\Config\SecretRedisReader

Declaration

class SecretRedisReader extends MagicObject\SecretObject { }

Package

MagicApp\Config

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class SecretRedisReader

This class is responsible for reading and decrypting sensitive Redis configuration details, such as server connection parameters. The class extends the SecretObject class, which ensures that sensitive data is decrypted securely when accessed.

The properties in this class are encrypted, and the @DecryptOut annotation is used to indicate that the values should be decrypted when read from storage (e.g., a database or configuration file).

This class provides secure access to Redis connection settings such as host, port, and password. It is designed to be used in applications that require secure management of Redis configuration parameters.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. host

Declaration

protected $host;

Description

Redis server host

2. port

Declaration

protected $port;

Description

Redis port

3. password

Declaration

protected $password;

Description

Redis password

4. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

5. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\Config\SecretRedisWriter

Declaration

class SecretRedisWriter extends MagicObject\SecretObject { }

Package

MagicApp\Config

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class SecretRedisWriter

This class is responsible for securely handling and encrypting Redis configuration details such as the server connection parameters. It extends the SecretObject class, which ensures that sensitive data is encrypted when being stored or written to persistent storage (e.g., a database or file system).

The properties in this class are encrypted using the @EncryptIn annotation to ensure that the sensitive data is encrypted before being stored.

This class provides secure access to Redis connection settings such as host, port, and password, and is designed to be used in applications that require the encryption of Redis configuration parameters before they are stored.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. host

Declaration

protected $host;

Description

Redis server host

2. port

Declaration

protected $port;

Description

Redis port

3. password

Declaration

protected $password;

Description

Redis password

4. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

5. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\Config\SecretSessionReader

Declaration

class SecretSessionReader extends MagicObject\SecretObject { }

Package

MagicApp\Config

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class SecretSessionReader

This class is responsible for securely handling and decrypting session configuration details such as session save handler and save path. It extends the SecretObject class, which ensures that sensitive data is decrypted when being read from persistent storage (e.g., a database or configuration file).

The properties in this class are decrypted using the @DecryptOut annotation to ensure that the sensitive data is decrypted when accessed.

This class provides secure access to session configuration settings such as the session save handler and path, and is designed to be used in applications that require the decryption of session-related configuration parameters.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. saveHandler

Declaration

protected $saveHandler;

Description

Session save handler

2. savePath

Declaration

protected $savePath;

Description

Session save path

3. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

4. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\Config\SecretSessionWriter

Declaration

class SecretSessionWriter extends MagicObject\SecretObject { }

Package

MagicApp\Config

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class SecretSessionWriter

This class is responsible for securely handling and encrypting session configuration details such as the session save handler and save path. It extends the SecretObject class, which ensures that sensitive data is encrypted before being written to persistent storage (e.g., a database or configuration file).

The properties in this class are encrypted using the @EncryptIn annotation to ensure that sensitive data is securely stored when being written.

This class provides secure access to session configuration settings, and is designed to be used in applications that require encryption of session-related configuration parameters before they are saved.

Constants

const JSON = 'JSON';
const YAML = 'Yaml';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_DEFAULT_VALUE = 'defaultValue';
const ANNOTATION_ENCRYPT_IN = 'EncryptIn';
const ANNOTATION_DECRYPT_IN = 'DecryptIn';
const ANNOTATION_ENCRYPT_OUT = 'EncryptOut';
const ANNOTATION_DECRYPT_OUT = 'DecryptOut';
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Properties

1. saveHandler

Declaration

protected $saveHandler;

Description

Session save handler

2. savePath

Declaration

protected $savePath;

Description

Session save path

3. _classParams

Declaration

protected array $_classParams = array();

Description

Class parameters.

The property name starts with an underscore to prevent child classes from overriding its value.

4. _nullProperties

Declaration

protected array $_nullProperties = array();

Description

NULL properties.

The property name starts with an underscore to prevent child classes from overriding its value.

Methods

1. __construct

Declaration

public function __construct(
    self|array|object|null $data = null,
    callable|null $secureCallback = null
)
{
}

Description

Constructor for initializing the object with data.

This constructor accepts initial data in various formats (array or object) and allows the optional specification of a callback function for secure key generation. The data is processed and loaded into the object upon instantiation.

Parameters

$data

The initial data for the object. Can be an

$secureCallback

An optional callback function for generating

2. _objectInfo

Declaration

private function _objectInfo() : void
{
}

Description

Analyzes the class's parameters and properties to determine which should be encrypted or decrypted based on annotations.

This method uses reflection to retrieve the class's parameters and properties. It then parses annotations associated with these members to identify which properties should undergo encryption or decryption during specific stages (before storage or before retrieval). The appropriate lists of properties are populated accordingly.

Return

void

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. secureKey

Declaration

private function secureKey() : string
{
}

Description

Generates a secure key for encryption and decryption.

This method checks for a user-defined secure key generation function. If a valid function is provided, it calls that function to generate the key. Otherwise, it returns a concatenation of predefined random keys.

Return

string

The secure key for encryption/decryption.

4. __call

Declaration

public function __call(
    string $method,
    array $params
) : mixed|null
{
}

Description

Magic method called when invoking undefined methods.

This method handles dynamic method calls for property management.

Supported methods:

  • isset<PropertyName>: Checks if the property is set.

    • Example: $obj->issetFoo() returns true if property foo is set.
  • is<PropertyName>: Checks if the property is set and equals 1 (truthy).

    • Example: $obj->isFoo() returns true if property foo is set and is equal to 1.
  • get<PropertyName>: Retrieves the value of the property.

    • Example: $value = $obj->getFoo() gets the value of property foo.
  • set<PropertyName>: Sets the value of the property.

    • Example: $obj->setFoo($value) sets the property foo to $value.
  • unset<PropertyName>: Unsets the property.

    • Example: $obj->unsetFoo() removes the property foo.
  • push<PropertyName>: Pushes a value onto an array property.

    • Example: $obj->pushFoo($value) adds $value to the array property foo.
  • pop<PropertyName>: Pops a value from an array property.

    • Example: $value = $obj->popFoo() removes and returns the last value from the array property foo.

Parameters

$method

Method name.

$params

Parameters for the method.

Return

mixed|null

The result of the method call or null if not applicable.

5. _set

Declaration

private function _set(
    string $var,
    mixed $value
) : self
{
}

Description

Set a value for the specified property.

This method sets the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

$value

The value to set.

Return

self
6. _get

Declaration

private function _get(
    string $var
) : mixed
{
}

Description

Get the value of the specified property.

This method retrieves the value of a property and applies encryption or decryption if necessary based on the defined property rules.

Parameters

$var

The name of the property.

Return

mixed

The value of the property.

7. _getValue

Declaration

private function _getValue(
    string $var
) : mixed
{
}

Description

Get the raw value of the specified property.

This method retrieves the raw value of a property without any encryption or decryption.

Parameters

$var

The name of the property.

Return

mixed

The raw value of the property, or null if not set.

8. typeObject

Declaration

private function typeObject(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of MagicObject or PicoGenericObject.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

9. typeStdClass

Declaration

private function typeStdClass(
    mixed $data
) : bool
{
}

Description

Check if the given data is an instance of self or stdClass.

Parameters

$data

The data to check.

Return

bool

True if the data is an instance, otherwise false.

10. encryptValue

Declaration

public function encryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string|number $data,
    string|null $hexKey = null
) : mixed
{
}

Description

Encrypt data recursively.

This method encrypts the provided data, which can be an object, array, or scalar value. It handles nested structures by encrypting each value individually.

Parameters

$data

The data to encrypt.

$hexKey

The encryption key in hexadecimal format. If null, a secure key will be generated.

Return

mixed

The encrypted data.

11. encryptString

Declaration

public function encryptString(
    string $plaintext,
    string|null $hexKey = null
) : string
{
}

Description

Encrypt a string.

This method encrypts a plain text string using a specified or generated secure key.

Parameters

$plaintext

The plain text to be encrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string

The encrypted string in base64 format.

12. decryptValue

Declaration

public function decryptValue(
    MagicObject|PicoGenericObject|self|array|stdClass|string $data,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt data recursively.

This method decrypts the provided ciphertext, which can be an object, array, or scalar value. It handles nested structures by decrypting each value individually.

Parameters

$data

The ciphertext to decrypt.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

13. decryptString

Declaration

public function decryptString(
    string $ciphertext,
    string|null $hexKey = null
) : string|null
{
}

Description

Decrypt a string.

This method decrypts a given ciphertext string using a specified or generated secure key.

Parameters

$ciphertext

The encrypted data to be decrypted.

$hexKey

The key in hexadecimal format. If null, a secure key will be generated.

Return

string|null

The decrypted string or null if decryption fails.

14. needInputEncryption

Declaration

private function needInputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

15. needOutputDecryption

Declaration

private function needOutputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

16. needOutputEncryption

Declaration

private function needOutputEncryption(
    string $var
) : bool
{
}

Description

Check if a value requires encryption after being read.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be encrypted, otherwise false.

17. needInputDecryption

Declaration

private function needInputDecryption(
    string $var
) : bool
{
}

Description

Check if a value requires decryption before being stored.

Parameters

$var

The variable name.

Return

bool

True if the value needs to be decrypted, otherwise false.

18. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Load data into the object.

This method populates the object's properties from the provided data, which can be an object, array, or scalar value.

Parameters

$data

The data to load.

Return

self

Returns the current instance for method chaining.

19. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

This method parses an INI formatted string and loads the data into the object.

Parameters

$rawData

The raw INI data as a string.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

20. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

This method reads an INI file and loads the data into the object.

Parameters

$path

The path to the INI file.

$systemEnv

Flag to indicate whether to use environment variable replacement.

Return

self

Returns the current instance for method chaining.

21. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

This method parses a YAML formatted string and loads the data into the object.

Parameters

$rawData

The YAML data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

22. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

This method reads a YAML file and loads the data into the object.

Parameters

$path

The path to the YAML file.

$systemEnv

Flag to indicate whether to replace environment variables.

$asObject

Flag to indicate whether to return results as an object.

$recursive

Flag to indicate whether to convert nested objects to MagicObject.

Return

self

Returns the current instance for method chaining.

23. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

This method parses a JSON formatted string and loads the data into the object.

Parameters

$rawData

The JSON data as a string.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

24. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON file.

This method reads a JSON file and loads the data into the object.

Parameters

$path

The path to the JSON file.

$systemEnv

Flag to indicate whether to replace environment variables.

$recursive

Flag to create recursive object.

Return

self

Returns the current instance for method chaining.

25. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the object to read-only mode.

When in read-only mode, setters will not change the value of the object's properties, but the loadData method will still work.

Parameters

$readonly

Flag to set the object to read-only.

Return

self

Returns the current instance for method chaining.

26. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue
) : self
{
}

Description

Set a property value.

Parameters

$propertyName

The name of the property to set.

$propertyValue

The value to set for the property.

Return

self

Returns the current instance for method chaining.

27. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Add an element to a property array.

Parameters

$propertyName

The name of the property.

$propertyValue

The value to add.

Return

self

Returns the current instance for method chaining.

28. pop

Declaration

public function pop(
    string $propertyName
) : mixed|null
{
}

Description

Remove the last element from a property array.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The removed value or null if the property is not an array.

29. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get a property value.

Parameters

$propertyName

The name of the property.

Return

mixed|null

The value of the property or null if not set.

30. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed
{
}

Description

Get a property value or return a default value if not set.

Parameters

$propertyName

The name of the property.

$defaultValue

The default value to return if the property is not set.

Return

mixed

The property value or the default value.

31. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copies values from another object to the current object based on specified filters.

This method allows selective copying of property values from a source object to the current object. You can specify which properties to copy using a filter, and you can choose whether to include properties with null values.

Parameters

$source

The source object from which to copy values.

$filter

An optional array of property names to filter which values

$includeNull

A flag indicating whether to include properties with null

Return

self

Returns the current instance for method chaining.

32. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value.

This method retrieves the values of the object's properties, optionally converting the property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

33. valueObject

Declaration

public function valueObject(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get object value as an object.

This method is an alias for the value() method, allowing for retrieval of object values, optionally in snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

stdClass

An object containing the values of the properties.

34. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get object value as an associative array.

This method retrieves the object values and converts them to an associative array, optionally converting property names to snake case.

Parameters

$snakeCase

Flag to convert property names to snake case.

Return

array

An associative array containing the values of the properties.

35. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get object value as an associative array with upper camel case keys.

This method retrieves the object values and converts them to an associative array, with keys formatted in upper camel case.

Return

array

An associative array containing the values of the properties with upper camel case keys.

36. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if JSON naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

37. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if YAML naming strategy is snake case.

Return

bool

True if the naming strategy is snake case, otherwise false.

38. isUpperCamel

Declaration

protected function isUpperCamel() : bool
{
}

Description

Check if JSON naming strategy is upper camel case.

Return

bool

True if the naming strategy is upper camel case, otherwise false.

39. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

40. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if JSON naming strategy is camel case.

Return

bool

True if the naming strategy is camel case, otherwise false.

41. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get the list of properties of the class.

This method returns an array of properties defined in the class, optionally reflecting the self class or converting the properties to an array.

Parameters

$reflectSelf

Flag to include properties defined in the current class.

$asArrayProps

Flag to return properties as an array.

Return

array

An array of ReflectionProperty objects or property names.

42. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify null properties.

This method keeps track of properties that have been set to null, allowing for tracking changes to properties.

Parameters

$propertyName

The name of the property.

$propertyValue

The value of the property.

Return

self

Returns the current instance for method chaining.

43. encryptedValue

Declaration

public function encryptedValue() : array
{
}

Description

Get the encrypted value of the object.

This method returns an array representation of the object's encrypted values.

Return

array

An array containing the encrypted values.

44. encryptValueRecursive

Declaration

private function encryptValueRecursive(
    array $array
) : array
{
}

Description

Encrypt values recursively.

This method encrypts each string value in the provided array. Nested arrays are also processed.

Parameters

$array

The array of values to be encrypted.

Return

array

The array with encrypted values.

45. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

This method attempts to convert an array into a friendly YAML format.

Parameters

$inline

The level where to switch to inline YAML. If set to NULL,

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

46. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

This method returns a JSON representation of the object.

Return

string

A JSON representation of the object.

MagicApp\Entity\AppModule

Declaration

class AppModule extends MagicObject\MagicObject { }

Package

MagicApp\Entity

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class AppModule

Represents an application module entity. This class is designed to be used as a part of the application's domain model, encapsulating the properties and behaviors related to a module within the app.

The AppModule class extends the MagicObject class, providing additional functionality such as serialization, deserialization, and possibly encryption/decryption, depending on the implementation of MagicObject.

This class can be used to represent various modules of an application, such as user management, content management, or other logical units that the application may be divided into.

Constants

const MESSAGE_NO_DATABASE_CONNECTION = 'No database connection provided';
const MESSAGE_NO_RECORD_FOUND = 'No record found';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_TYPE = 'type';
const KEY_LENGTH = 'length';
const KEY_DEFAULT_VALUE = 'defaultValue';
const JSON = 'JSON';
const YAML = 'Yaml';
const ATTR_CHECKED = ' checked="checked"';
const ATTR_SELECTED = ' selected="selected"';
const FIND_OPTION_DEFAULT = 0;
const FIND_OPTION_NO_COUNT_DATA = 1;
const FIND_OPTION_NO_FETCH_DATA = 2;
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Methods

1. nullPropertyList

Declaration

public function nullPropertyList() : array
{
}

Description

Retrieves the list of null properties.

Return

array

The list of properties that are currently null.

2. __construct

Declaration

public function __construct(
    self|array|stdClass|object|null $data = null,
    PicoDatabase|PDO|null $database = null
)
{
}

Description

Constructor.

Initializes the object with the provided data and optionally connects to a database. The constructor can accept different types of data to populate the object and can also accept a PDO connection or a PicoDatabase instance to set up the database connection.

Parameters

$data

Initial data to populate the object. This can be:

$database

A database connection instance, either:

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Loads data into the object.

Parameters

$data

Data to load, which can be another MagicObject, an array, or an object.

Return

self

Returns the current instance for method chaining.

4. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

Parameters

$rawData

Raw INI data

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

5. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

Parameters

$path

File path to the INI file

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

6. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

Parameters

$rawData

YAML string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

7. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

Parameters

$path

File path to the YAML file

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

8. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

Parameters

$rawData

JSON string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

9. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Loads data from a JSON file and processes it based on the provided options.

Parameters

$path

The file path to the JSON file.

$systemEnv

Whether to replace system environment variables in the data (default: false).

$asObject

Whether to return the result as an object instead of an associative array (default: false).

$recursive

Whether to recursively convert all objects into MagicObject instances (default: false).

Return

self

Returns the current instance for method chaining.

Throws

FileNotFoundException

If the specified JSON file does not exist.

10. loadJsonData

Declaration

private function loadJsonData(
    mixed $data,
    bool $asObject,
    bool $recursive
) : self
{
}

Description

Loads processed JSON data and optionally converts it to objects or parses recursively.

Parameters

$data

The processed data to load (array or object).

$asObject

Whether to return the result as an object.

$recursive

Whether to recursively convert all objects into MagicObject instances.

Return

self

Returns the current instance for method chaining.

11. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the read-only state of the object.

When set to read-only, setters will not change the value of its properties, but loadData will still function normally.

Parameters

$readonly

Flag to set the object as read-only

Return

self

Returns the current instance for method chaining.

12. _databaseConnected

Declaration

private function _databaseConnected() : bool
{
}

Description

Check if database is connected or not

Return

bool

Returns true if the database is connected, false otherwise.

13. withDatabase

Declaration

public function withDatabase(
    PicoDatabase $database
) : self
{
}

Description

Set the database connection.

Parameters

$database

Database connection

Return

self

Returns the current instance for method chaining.

14. currentDatabase

Declaration

public function currentDatabase(
    PicoDatabase|null $database = null
) : PicoDatabase|null
{
}

Description

Set or get the current database connection.

If the parameter is not empty, set the current database to the provided value. Otherwise, return the current database or null.

Parameters

$database

Database connection

Return

PicoDatabase|null
15. databaseEntity

Declaration

public function databaseEntity(
    MagicObject|PicoDatabaseEntity|null $databaseEntity = null
) : self|PicoDatabaseEntity
{
}

Description

Set or get the database entity.

If a database entity is provided, it will be set; otherwise, the current database entity will be returned.

Parameters

$databaseEntity

The database entity to set or null to get the current entity.

Return

self|PicoDatabaseEntity

Returns the current instance for method chaining, or the current database entity if no parameter is provided.

16. removePropertyExcept

Declaration

public function removePropertyExcept(
    object|array $sourceData,
    array $propertyNames
) : object|array
{
}

Description

Remove properties except for the specified ones.

Parameters

$sourceData

Data to filter

$propertyNames

Names of properties to retain

Return

object|array

Filtered data

17. save

Declaration

public function save(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Save the current object to the database.

This method persists the current object to the database. If $includeNull is TRUE, all properties of the object, including those with null values, will be saved. If FALSE, only the properties with non-null values will be saved.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

PDOException

If a database error occurs.

18. saveQuery

Declaration

public function saveQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to save data to the database.

This method prepares a query to persist the current object to the database. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only properties with non-null values will be included.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for query construction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

19. select

Declaration

public function select() : self
{
}

Description

Select data from the database.

This method retrieves data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

20. selectAll

Declaration

public function selectAll() : self
{
}

Description

Select all data from the database.

This method retrieves all data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

21. selectQuery

Declaration

public function selectQuery() : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to select data.

This method prepares a query to select data from the database. The query can then be used to execute the retrieval of data manually if needed.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the select query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If a database error occurs.

22. executeNativeQuery

Declaration

protected function executeNativeQuery() : mixed
{
}

Description

Executes a database query based on the parameters and annotations from the caller function.

This method uses reflection to extract the query string and return type from the caller's docblock, binds the provided parameters, and executes the query against the database.

It analyzes the parameters and return type of the caller function to enable dynamic query execution tailored to the specified return type. Supported return types include:

  • void: Returns null.
  • int or integer: Returns the number of affected rows.
  • object or stdClass: Returns a single result as an object.
  • stdClass[]: Returns all results as an array of stdClass objects.
  • array: Returns all results as an associative array.
  • string: Returns the JSON-encoded results.
  • PDOStatement: Returns the prepared statement for further operations if needed.
  • MagicObject and its derived classes: If the return type is a class name or an array of class names, instances of that class will be created for each row fetched.
  • MagicObject[] and its derived classes: Instances of the corresponding class will be created for each row fetched.

Return

mixed

The result based on the return type of the caller function:

Throws

PDOException

If there is an error executing the database query.

InvalidQueryInputException

If there is no query to be executed or if the input is invalid.

InvalidReturnTypeException

If the return type specified in the docblock is invalid or unrecognized.

23. insert

Declaration

public function insert(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Insert data into the database.

This method inserts the current objectΓÇÖs data into the database. If $includeNull is TRUE, properties with null values will also be included in the insert query. If FALSE, only properties with non-null values will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be inserted. If FALSE, only non-null values will be inserted.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the insert query.

24. insertQuery

Declaration

public function insertQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for inserting data.

This method prepares a query to insert data into the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only non-null properties will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the insert query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the insert query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

25. update

Declaration

public function update(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Update data in the database.

This method updates the current object's data in the database. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only properties with non-null values will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be updated. If FALSE, only non-null values will be updated.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the update query.

26. updateQuery

Declaration

public function updateQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for updating data.

This method prepares a query to update data in the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only non-null properties will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the update query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the update query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

27. delete

Declaration

public function delete() : PDOStatement
{
}

Description

Delete data from the database.

This method deletes data associated with the current object from the database.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the delete query.

28. deleteQuery

Declaration

public function deleteQuery() : PicoDatabaseQueryBuilder
{
}

Description

Get the query for deleting data.

This method prepares a query to delete data from the database. It can be used to manually execute the query.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the delete query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

29. startTransaction

Declaration

public function startTransaction() : self
{
}

Description

Starts a database transaction.

This method begins a new database transaction. It delegates the actual transaction initiation to the transactionalCommand method, passing the "start" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error while starting the transaction.

30. commit

Declaration

public function commit() : self
{
}

Description

Commits the current database transaction.

This method commits the current transaction. If successful, it makes all database changes made during the transaction permanent. It delegates to the transactionalCommand method with the "commit" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the commit process.

31. rollback

Declaration

public function rollback() : self
{
}

Description

Rolls back the current database transaction.

This method rolls back the current transaction, undoing all database changes made during the transaction. It calls the transactionalCommand method with the "rollback" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the rollback process.

32. where

Declaration

public function where(
    PicoSpecification $specification
) : PicoDatabasePersistenceExtended
{
}

Description

Get a MagicObject with a WHERE specification.

This method applies a WHERE condition to the database query using the provided specification. The specification is an instance of PicoSpecification which defines the filtering criteria.

Parameters

$specification

The specification to define the WHERE condition.

Return

PicoDatabasePersistenceExtended

Returns an instance of PicoDatabasePersistenceExtended

Throws

NoDatabaseConnectionException

If there is no active database connection.

33. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify properties with null values.

This method tracks properties that are assigned a null value, storing them in a _nullProperties array. If a property is set to null, it is added to the _nullProperties array; if it's set to a non-null value, it is removed from the array.

Parameters

$propertyName

The name of the property to check and modify.

$propertyValue

The value to be assigned to the property.

Return

self

Returns the current instance for method chaining.

34. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Set property value.

Parameters

$propertyName

Property name

$propertyValue

Property value

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

35. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

36. append

Declaration

public function append(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property (alias for push).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

37. unshift

Declaration

public function unshift(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

38. prepend

Declaration

public function prepend(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property (alias for unshift).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

39. pop

Declaration

public function pop(
    string $propertyName
) : mixed
{
}

Description

Remove and return the last element of an array property.

This method removes the last element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the last element will be removed.

Return

mixed

The last element of the array, or null if the property is not an array or doesn't exist.

40. shift

Declaration

public function shift(
    string $propertyName
) : mixed
{
}

Description

Remove and return the first element of an array property.

This method removes the first element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the first element will be removed.

Return

mixed

The first element of the array, or null if the property is not an array or doesn't exist.

41. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get the value of a property.

This method retrieves the value of the specified property. If the property does not exist, it returns null.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property, or null if the property is not set.

42. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed|null
{
}

Description

Get the value of a property or a default value if the property is not set.

This method retrieves the value of the specified property. If the property is not set, the provided default value is returned.

Parameters

$propertyName

The name of the property to retrieve.

$defaultValue

The default value to return if the property is not set.

Return

mixed|null

The value of the property, or the default value if the property is not set.

43. __set

Declaration

public function __set(
    string $propertyName,
    mixed $propertyValue
)
{
}

Description

Set property value (magic setter).

Parameters

$propertyName

Property name

$propertyValue

Property value

44. __get

Declaration

public function __get(
    string $propertyName
) : mixed|null
{
}

Description

Magic method to get the value of a property.

This method is automatically called when an undefined or inaccessible property is accessed. It checks if the property has been set (including null values) using the __isset method and retrieves its value via the get method if it exists.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property if it is set, or null if the property is not set or accessible.

45. __isset

Declaration

public function __isset(
    string $propertyName
) : bool
{
}

Description

Magic method to check if a property is set (including null).

This method is automatically called when checking if an undefined or inaccessible property is set using isset(). It checks if the property exists and is set (even if its value is null).

Parameters

$propertyName

The name of the property to check.

Return

bool

True if the property is set (including null), false otherwise.

46. __unset

Declaration

public function __unset(
    string $propertyName
) : void
{
}

Description

Magic method to unset a property.

This method is automatically called when a property is unset using unset(). It unsets the specified property from the object.

Parameters

$propertyName

The name of the property to unset.

Return

void
47. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copy values from another object to the current instance.

This method copies property values from the provided source object to the current instance. Optionally, a filter can be applied to specify which properties to copy, and whether null values should be included.

Parameters

$source

The source object or data from which values will be copied. If a non-object is provided, this may result in unexpected behavior.

$filter

An optional array of property names to filter which properties are copied. If null, all properties are copied.

$includeNull

Flag indicating whether to include properties with null values. If false, properties with null values will be excluded from the copy.

Return

self

Returns the current instance for method chaining after copying the values.

48. removeValue

Declaration

private function removeValue(
    string $propertyName,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Remove property value and set it to null.

Parameters

$propertyName

Property name

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

49. tableInfo

Declaration

public function tableInfo() : PicoTableInfo
{
}

Description

Retrieve table information for the current instance.

This method retrieves the table information (e.g., schema, columns) associated with the current object. It lazily loads the table information, meaning it will be fetched only once and cached for future calls to improve performance.

Return

PicoTableInfo

Returns an instance of the PicoTableInfo class containing the table schema and other related metadata.

50. defaultValue

Declaration

public function defaultValue(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get default values for properties

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing default values

51. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get the object values

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing the values of the properties

52. valueObject

Declaration

public function valueObject(
    boolean|null $snakeCase = null
) : stdClass
{
}

Description

Get the object value as a specified format

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case; if null, default behavior is used

Return

stdClass

An object representing the value of the instance

53. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get the object value as an associative array

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

array

An associative array representing the object values

54. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get the object value as an associative array with the first letter of each key in upper camel case

Return

array

An associative array with keys in upper camel case

55. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if the JSON naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

56. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if the YAML naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

57. _upperCamel

Declaration

protected function _upperCamel() : bool
{
}

Description

Check if the JSON naming strategy is upper camel case

Return

bool

True if the naming strategy is upper camel case; otherwise, false

58. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if the JSON naming strategy is camel case

Return

bool

True if the naming strategy is camel case; otherwise, false

59. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

60. _isArray

Declaration

private function _isArray(
    mixed $params
) : bool
{
}

Description

Checks if the provided parameter is an array.

This function verifies if the given parameter is set and is of type array. It is a helper method used to validate the type of data before performing any operations on it that require an array.

Parameters

$params

The parameter to check.

Return

bool

Returns true if the parameter is set and is an array, otherwise returns false.

61. _isNotNullAndNotEmpty

Declaration

private function _isNotNullAndNotEmpty(
    mixed $value
) : bool
{
}

Description

Check if a value is not null and not empty

Parameters

$value

The value to check

Return

bool

True if the value is not null and not empty; otherwise, false

62. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get a list of properties

Parameters

$reflectSelf

Flag indicating whether to reflect properties of the current class

$asArrayProps

Flag indicating whether to return properties as an array

Return

array

An array of property names or ReflectionProperty objects

63. listAll

Declaration

public function listAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null
) : PicoPageData
{
}

Description

List all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

64. countData

Declaration

private function countData(
    PicoDatabasePersistence $persist,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable,
    PicoSortable|string|null $sortable,
    int $findOption = 0,
    array|null $result = null
) : int
{
}

Description

Count the data based on specifications

Parameters

$persist

The persistence object

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$findOption

The find option

$result

The result set

Return

int

The count of matching records

65. findOne

Declaration

public function findOne(
    PicoSpecification|null $specification = null,
    PicoSortable|string|null $sortable = null,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record based on specifications

Parameters

$specification

The specification for filtering

$sortable

The sorting criteria

$subqueryMap

An optional map of subqueries

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

66. findAll

Declaration

public function findAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

67. findAllAsc

Declaration

public function findAllAsc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in ascending order

Return

PicoPageData

The paginated data

68. findAllDesc

Declaration

public function findAllDesc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in descending order

Return

PicoPageData

The paginated data

69. findSpecific

Declaration

public function findSpecific(
    string $selected,
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find specific records

Parameters

$selected

The selected field(s)

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

70. countAll

Declaration

public function countAll(
    PicoSpecification|null $specification = null,
    PicoPageable|null $pageable = null,
    PicoSortable|null $sortable = null
) : int|false
{
}

Description

Count all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

int|false

The count of records or false on error

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

71. findAllQuery

Declaration

public function findAllQuery(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null
) : PicoDatabaseQueryBuilder
{
}

Description

Build a query to find all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

PicoDatabaseQueryBuilder

The query builder

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

72. find

Declaration

public function find(
    mixed $params
) : self
{
}

Description

Find one record by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

73. findIfExists

Declaration

public function findIfExists(
    array $params
) : self
{
}

Description

Find one record if it exists by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance. or the current instance if not found

74. findBy

Declaration

private function findBy(
    string $method,
    mixed $params,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap,
    int $findOption
) : PicoPageData
{
}

Description

Find records by specified parameters

Parameters

$method

The method to find by

$params

The parameters for the search

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

75. countBy

Declaration

private function countBy(
    string $method,
    mixed $params
) : int
{
}

Description

Count data from the database.

Parameters

$method

The method used for finding.

$params

The parameters to use for the count.

Return

int

The count of matching records.

Throws

NoDatabaseConnectionException

If there is no database connection.

76. deleteBy

Declaration

private function deleteBy(
    string $method,
    mixed $params
) : int
{
}

Description

Delete records based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

int

The number of deleted records.

Throws

NoDatabaseConnectionException

If there is no database connection.

77. findOneWithPrimaryKeyValue

Declaration

public function findOneWithPrimaryKeyValue(
    mixed $primaryKeyVal,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record using the primary key value.

Parameters

$primaryKeyVal

The primary key value.

$subqueryMap

Optional subquery map for additional queries.

Return

self

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

78. findOneBy

Declaration

private function findOneBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

79. findOneIfExistsBy

Declaration

private function findOneIfExistsBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record if it exists based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance or the current instance if not found.

Throws

NoDatabaseConnectionException

If there is no database connection.

80. deleteOneBy

Declaration

private function deleteOneBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Delete one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

bool

True on success; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

81. existsBy

Declaration

private function existsBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Check if a record exists based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

Return

bool

True if the record exists; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

82. booleanToTextBy

Declaration

private function booleanToTextBy(
    string $propertyName,
    string[] $params
) : string
{
}

Description

Convert a boolean value to text based on the specified property name.

Parameters

$propertyName

The property name to check.

$params

The text representations for true and false.

Return

string

The corresponding text representation.

83. toArrayObject

Declaration

private function toArrayObject(
    array $result,
    bool $passive = false
) : array
{
}

Description

Convert the result to an array of objects.

Parameters

$result

The result set to convert.

$passive

Flag indicating whether the objects are passive.

Return

array

An array of objects.

84. size

Declaration

public function size() : int
{
}

Description

Get the number of properties of the object.

Return

int

The number of properties.

85. __call

Declaration

public function __call(
    string $method,
    mixed $params
) : mixed|null
{
}

Description

Magic method called when a user calls any undefined method. The __call method checks the prefix of the called method and invokes the appropriate method according to its name and parameters.

Method Descriptions:

  • hasValue: Checks if the property has a value.

    • Example: $object->hasValuePropertyName();
  • isset: Checks if the property is set.

    • Example: $object->issetPropertyName();
  • is: Retrieves the property value as a boolean.

    • Example: $isActive = $object->isActive();
  • equals: Checks if the property value equals the given value.

    • Example: $isEqual = $object->equalsPropertyName($value);
  • get: Retrieves the property value.

    • Example: $value = $object->getPropertyName();
  • set: Sets the property value.

    • Example: $object->setPropertyName($value);
  • unset: Unsets the property value.

    • Example: $object->unsetPropertyName();
  • push: Adds array elements to a property at the end.

    • Example: $object->pushPropertyName($newElement);
  • append: Appends array elements to a property at the end.

    • Example: $object->appendPropertyName($newElement);
  • unshift: Adds array elements to a property at the beginning.

    • Example: $object->unshiftPropertyName($newElement);
  • prepend: Prepends array elements to a property at the beginning.

    • Example: $object->prependPropertyName($newElement);
  • pop: Removes the last element from the property.

    • Example: $removedElement = $object->popPropertyName();
  • shift: Removes the first element from the property.

    • Example: $removedElement = $object->shiftPropertyName();
  • findOneBy: Searches for data in the database and returns one record.

    • Example: $record = $object->findOneByPropertyName($value);
    • Requires a database connection.
  • findOneIfExistsBy: Searches for data in the database by any column values and returns one record.

    • Example: $record = $object->findOneIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • deleteOneBy: Deletes data from the database by any column values and returns one record.

    • Example: $deletedRecord = $object->deleteOneByPropertyName($value, $sortable);
    • Requires a database connection.
  • findFirstBy: Searches for data in the database by any column values and returns the first record.

    • Example: $firstRecord = $object->findFirstByColumnName($value);
    • Requires a database connection.
  • findFirstIfExistsBy: Similar to findFirstBy, but returns the first record if it exists.

    • Example: $firstRecord = $object->findFirstIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findLastBy: Searches for data in the database by any column values and returns the last record.

    • Example: $lastRecord = $object->findLastByColumnName($value);
    • Requires a database connection.
  • findLastIfExistsBy: Similar to findLastBy, but returns the last record if it exists.

    • Example: $lastRecord = $object->findLastIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findBy: Searches for multiple records in the database by any column values.

    • Example: $records = $object->findByColumnName($value);
    • Requires a database connection.
  • countBy: Counts data from the database.

    • Example: $count = $object->countByColumnName();
  • existsBy: Checks for data in the database.

    • Example: $exists = $object->existsByColumn($column);
    • Requires a database connection.
  • deleteBy: Deletes data from the database without reading it first.

    • Example: $object->deleteByPropertyName($value);
    • Requires a database connection.
  • booleanToTextBy: Converts a boolean value to "yes/no" or "true/false" based on given parameters.

    • Example: $result = $object->booleanToTextByActive("Yes", "No");
    • If $obj->active is true, $result will be "Yes"; otherwise, it will be "No".
  • startsWith: Checks if the value starts with a given string.

    • Example: $startsWith = $object->startsWithPropertyName("prefix");
  • endsWith: Checks if the value ends with a given string.

    • Example: $endsWith = $object->endsWithPropertyName("suffix");
  • label: Retrieves the label associated with the given property.

    • If the label is not set, it attempts to fetch it from annotations.
    • Example: $label = $object->labelPropertyName();
  • option: Returns the first parameter if the property is set to true or equals 1; otherwise returns the second parameter.

    • Example: $option = $object->optionPropertyName("Yes", "No");
  • notNull: Checks if the specified property is set (not null).

    • Example: $isNotNull = $object->notNullPropertyName();
  • notEmpty: Checks if the specified property is set and not empty.

    • Example: $isNotEmpty = $object->notEmptyPropertyName();
  • notZero: Checks if the specified property is set and not equal to zero.

    • Example: $isNotZero = $object->notZeroPropertyName();
  • notEquals: Checks if the specified property is set and does not equal the given value.

    • Example: $isNotEqual = $object->notEqualsPropertyName($value);

Parameters

$method

Method name

$params

Parameters for the method

Return

mixed|null

The result of the called method, or null if not applicable

86. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

Return

string

A JSON representation of the object.

87. stringifyObject

Declaration

private function stringifyObject(
    self $value,
    bool $snake
) : mixed
{
}

Description

Recursively stringify an object or array of objects.

Parameters

$value

The object to stringify.

$snake

Flag to indicate whether to convert property names to snake_case.

Return

mixed

The stringified object or array.

88. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

The dump method, when supplied with an array, converts it into a friendly YAML format.

Parameters

$inline

The level at which to switch to inline YAML. If NULL, the maximum depth will be used.

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

MagicApp\Entity\AppModuleGroup

Declaration

class AppModuleGroup extends MagicObject\MagicObject { }

Package

MagicApp\Entity

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class AppModuleGroup

Represents a group of application modules. This class serves as a container or organizational unit for managing multiple modules within the application.

The AppModuleGroup class extends the MagicObject class, allowing it to inherit functionalities such as serialization, deserialization, and possibly encryption/decryption, depending on the implementation of MagicObject.

This class can be used to logically group related application modules together, allowing for easier management and organization of the application's structure.

Constants

const MESSAGE_NO_DATABASE_CONNECTION = 'No database connection provided';
const MESSAGE_NO_RECORD_FOUND = 'No record found';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_TYPE = 'type';
const KEY_LENGTH = 'length';
const KEY_DEFAULT_VALUE = 'defaultValue';
const JSON = 'JSON';
const YAML = 'Yaml';
const ATTR_CHECKED = ' checked="checked"';
const ATTR_SELECTED = ' selected="selected"';
const FIND_OPTION_DEFAULT = 0;
const FIND_OPTION_NO_COUNT_DATA = 1;
const FIND_OPTION_NO_FETCH_DATA = 2;
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Methods

1. nullPropertyList

Declaration

public function nullPropertyList() : array
{
}

Description

Retrieves the list of null properties.

Return

array

The list of properties that are currently null.

2. __construct

Declaration

public function __construct(
    self|array|stdClass|object|null $data = null,
    PicoDatabase|PDO|null $database = null
)
{
}

Description

Constructor.

Initializes the object with the provided data and optionally connects to a database. The constructor can accept different types of data to populate the object and can also accept a PDO connection or a PicoDatabase instance to set up the database connection.

Parameters

$data

Initial data to populate the object. This can be:

$database

A database connection instance, either:

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Loads data into the object.

Parameters

$data

Data to load, which can be another MagicObject, an array, or an object.

Return

self

Returns the current instance for method chaining.

4. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

Parameters

$rawData

Raw INI data

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

5. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

Parameters

$path

File path to the INI file

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

6. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

Parameters

$rawData

YAML string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

7. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

Parameters

$path

File path to the YAML file

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

8. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

Parameters

$rawData

JSON string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

9. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Loads data from a JSON file and processes it based on the provided options.

Parameters

$path

The file path to the JSON file.

$systemEnv

Whether to replace system environment variables in the data (default: false).

$asObject

Whether to return the result as an object instead of an associative array (default: false).

$recursive

Whether to recursively convert all objects into MagicObject instances (default: false).

Return

self

Returns the current instance for method chaining.

Throws

FileNotFoundException

If the specified JSON file does not exist.

10. loadJsonData

Declaration

private function loadJsonData(
    mixed $data,
    bool $asObject,
    bool $recursive
) : self
{
}

Description

Loads processed JSON data and optionally converts it to objects or parses recursively.

Parameters

$data

The processed data to load (array or object).

$asObject

Whether to return the result as an object.

$recursive

Whether to recursively convert all objects into MagicObject instances.

Return

self

Returns the current instance for method chaining.

11. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the read-only state of the object.

When set to read-only, setters will not change the value of its properties, but loadData will still function normally.

Parameters

$readonly

Flag to set the object as read-only

Return

self

Returns the current instance for method chaining.

12. _databaseConnected

Declaration

private function _databaseConnected() : bool
{
}

Description

Check if database is connected or not

Return

bool

Returns true if the database is connected, false otherwise.

13. withDatabase

Declaration

public function withDatabase(
    PicoDatabase $database
) : self
{
}

Description

Set the database connection.

Parameters

$database

Database connection

Return

self

Returns the current instance for method chaining.

14. currentDatabase

Declaration

public function currentDatabase(
    PicoDatabase|null $database = null
) : PicoDatabase|null
{
}

Description

Set or get the current database connection.

If the parameter is not empty, set the current database to the provided value. Otherwise, return the current database or null.

Parameters

$database

Database connection

Return

PicoDatabase|null
15. databaseEntity

Declaration

public function databaseEntity(
    MagicObject|PicoDatabaseEntity|null $databaseEntity = null
) : self|PicoDatabaseEntity
{
}

Description

Set or get the database entity.

If a database entity is provided, it will be set; otherwise, the current database entity will be returned.

Parameters

$databaseEntity

The database entity to set or null to get the current entity.

Return

self|PicoDatabaseEntity

Returns the current instance for method chaining, or the current database entity if no parameter is provided.

16. removePropertyExcept

Declaration

public function removePropertyExcept(
    object|array $sourceData,
    array $propertyNames
) : object|array
{
}

Description

Remove properties except for the specified ones.

Parameters

$sourceData

Data to filter

$propertyNames

Names of properties to retain

Return

object|array

Filtered data

17. save

Declaration

public function save(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Save the current object to the database.

This method persists the current object to the database. If $includeNull is TRUE, all properties of the object, including those with null values, will be saved. If FALSE, only the properties with non-null values will be saved.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

PDOException

If a database error occurs.

18. saveQuery

Declaration

public function saveQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to save data to the database.

This method prepares a query to persist the current object to the database. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only properties with non-null values will be included.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for query construction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

19. select

Declaration

public function select() : self
{
}

Description

Select data from the database.

This method retrieves data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

20. selectAll

Declaration

public function selectAll() : self
{
}

Description

Select all data from the database.

This method retrieves all data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

21. selectQuery

Declaration

public function selectQuery() : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to select data.

This method prepares a query to select data from the database. The query can then be used to execute the retrieval of data manually if needed.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the select query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If a database error occurs.

22. executeNativeQuery

Declaration

protected function executeNativeQuery() : mixed
{
}

Description

Executes a database query based on the parameters and annotations from the caller function.

This method uses reflection to extract the query string and return type from the caller's docblock, binds the provided parameters, and executes the query against the database.

It analyzes the parameters and return type of the caller function to enable dynamic query execution tailored to the specified return type. Supported return types include:

  • void: Returns null.
  • int or integer: Returns the number of affected rows.
  • object or stdClass: Returns a single result as an object.
  • stdClass[]: Returns all results as an array of stdClass objects.
  • array: Returns all results as an associative array.
  • string: Returns the JSON-encoded results.
  • PDOStatement: Returns the prepared statement for further operations if needed.
  • MagicObject and its derived classes: If the return type is a class name or an array of class names, instances of that class will be created for each row fetched.
  • MagicObject[] and its derived classes: Instances of the corresponding class will be created for each row fetched.

Return

mixed

The result based on the return type of the caller function:

Throws

PDOException

If there is an error executing the database query.

InvalidQueryInputException

If there is no query to be executed or if the input is invalid.

InvalidReturnTypeException

If the return type specified in the docblock is invalid or unrecognized.

23. insert

Declaration

public function insert(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Insert data into the database.

This method inserts the current objectΓÇÖs data into the database. If $includeNull is TRUE, properties with null values will also be included in the insert query. If FALSE, only properties with non-null values will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be inserted. If FALSE, only non-null values will be inserted.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the insert query.

24. insertQuery

Declaration

public function insertQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for inserting data.

This method prepares a query to insert data into the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only non-null properties will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the insert query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the insert query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

25. update

Declaration

public function update(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Update data in the database.

This method updates the current object's data in the database. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only properties with non-null values will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be updated. If FALSE, only non-null values will be updated.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the update query.

26. updateQuery

Declaration

public function updateQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for updating data.

This method prepares a query to update data in the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only non-null properties will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the update query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the update query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

27. delete

Declaration

public function delete() : PDOStatement
{
}

Description

Delete data from the database.

This method deletes data associated with the current object from the database.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the delete query.

28. deleteQuery

Declaration

public function deleteQuery() : PicoDatabaseQueryBuilder
{
}

Description

Get the query for deleting data.

This method prepares a query to delete data from the database. It can be used to manually execute the query.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the delete query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

29. startTransaction

Declaration

public function startTransaction() : self
{
}

Description

Starts a database transaction.

This method begins a new database transaction. It delegates the actual transaction initiation to the transactionalCommand method, passing the "start" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error while starting the transaction.

30. commit

Declaration

public function commit() : self
{
}

Description

Commits the current database transaction.

This method commits the current transaction. If successful, it makes all database changes made during the transaction permanent. It delegates to the transactionalCommand method with the "commit" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the commit process.

31. rollback

Declaration

public function rollback() : self
{
}

Description

Rolls back the current database transaction.

This method rolls back the current transaction, undoing all database changes made during the transaction. It calls the transactionalCommand method with the "rollback" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the rollback process.

32. where

Declaration

public function where(
    PicoSpecification $specification
) : PicoDatabasePersistenceExtended
{
}

Description

Get a MagicObject with a WHERE specification.

This method applies a WHERE condition to the database query using the provided specification. The specification is an instance of PicoSpecification which defines the filtering criteria.

Parameters

$specification

The specification to define the WHERE condition.

Return

PicoDatabasePersistenceExtended

Returns an instance of PicoDatabasePersistenceExtended

Throws

NoDatabaseConnectionException

If there is no active database connection.

33. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify properties with null values.

This method tracks properties that are assigned a null value, storing them in a _nullProperties array. If a property is set to null, it is added to the _nullProperties array; if it's set to a non-null value, it is removed from the array.

Parameters

$propertyName

The name of the property to check and modify.

$propertyValue

The value to be assigned to the property.

Return

self

Returns the current instance for method chaining.

34. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Set property value.

Parameters

$propertyName

Property name

$propertyValue

Property value

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

35. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

36. append

Declaration

public function append(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property (alias for push).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

37. unshift

Declaration

public function unshift(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

38. prepend

Declaration

public function prepend(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property (alias for unshift).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

39. pop

Declaration

public function pop(
    string $propertyName
) : mixed
{
}

Description

Remove and return the last element of an array property.

This method removes the last element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the last element will be removed.

Return

mixed

The last element of the array, or null if the property is not an array or doesn't exist.

40. shift

Declaration

public function shift(
    string $propertyName
) : mixed
{
}

Description

Remove and return the first element of an array property.

This method removes the first element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the first element will be removed.

Return

mixed

The first element of the array, or null if the property is not an array or doesn't exist.

41. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get the value of a property.

This method retrieves the value of the specified property. If the property does not exist, it returns null.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property, or null if the property is not set.

42. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed|null
{
}

Description

Get the value of a property or a default value if the property is not set.

This method retrieves the value of the specified property. If the property is not set, the provided default value is returned.

Parameters

$propertyName

The name of the property to retrieve.

$defaultValue

The default value to return if the property is not set.

Return

mixed|null

The value of the property, or the default value if the property is not set.

43. __set

Declaration

public function __set(
    string $propertyName,
    mixed $propertyValue
)
{
}

Description

Set property value (magic setter).

Parameters

$propertyName

Property name

$propertyValue

Property value

44. __get

Declaration

public function __get(
    string $propertyName
) : mixed|null
{
}

Description

Magic method to get the value of a property.

This method is automatically called when an undefined or inaccessible property is accessed. It checks if the property has been set (including null values) using the __isset method and retrieves its value via the get method if it exists.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property if it is set, or null if the property is not set or accessible.

45. __isset

Declaration

public function __isset(
    string $propertyName
) : bool
{
}

Description

Magic method to check if a property is set (including null).

This method is automatically called when checking if an undefined or inaccessible property is set using isset(). It checks if the property exists and is set (even if its value is null).

Parameters

$propertyName

The name of the property to check.

Return

bool

True if the property is set (including null), false otherwise.

46. __unset

Declaration

public function __unset(
    string $propertyName
) : void
{
}

Description

Magic method to unset a property.

This method is automatically called when a property is unset using unset(). It unsets the specified property from the object.

Parameters

$propertyName

The name of the property to unset.

Return

void
47. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copy values from another object to the current instance.

This method copies property values from the provided source object to the current instance. Optionally, a filter can be applied to specify which properties to copy, and whether null values should be included.

Parameters

$source

The source object or data from which values will be copied. If a non-object is provided, this may result in unexpected behavior.

$filter

An optional array of property names to filter which properties are copied. If null, all properties are copied.

$includeNull

Flag indicating whether to include properties with null values. If false, properties with null values will be excluded from the copy.

Return

self

Returns the current instance for method chaining after copying the values.

48. removeValue

Declaration

private function removeValue(
    string $propertyName,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Remove property value and set it to null.

Parameters

$propertyName

Property name

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

49. tableInfo

Declaration

public function tableInfo() : PicoTableInfo
{
}

Description

Retrieve table information for the current instance.

This method retrieves the table information (e.g., schema, columns) associated with the current object. It lazily loads the table information, meaning it will be fetched only once and cached for future calls to improve performance.

Return

PicoTableInfo

Returns an instance of the PicoTableInfo class containing the table schema and other related metadata.

50. defaultValue

Declaration

public function defaultValue(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get default values for properties

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing default values

51. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get the object values

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing the values of the properties

52. valueObject

Declaration

public function valueObject(
    boolean|null $snakeCase = null
) : stdClass
{
}

Description

Get the object value as a specified format

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case; if null, default behavior is used

Return

stdClass

An object representing the value of the instance

53. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get the object value as an associative array

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

array

An associative array representing the object values

54. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get the object value as an associative array with the first letter of each key in upper camel case

Return

array

An associative array with keys in upper camel case

55. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if the JSON naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

56. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if the YAML naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

57. _upperCamel

Declaration

protected function _upperCamel() : bool
{
}

Description

Check if the JSON naming strategy is upper camel case

Return

bool

True if the naming strategy is upper camel case; otherwise, false

58. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if the JSON naming strategy is camel case

Return

bool

True if the naming strategy is camel case; otherwise, false

59. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

60. _isArray

Declaration

private function _isArray(
    mixed $params
) : bool
{
}

Description

Checks if the provided parameter is an array.

This function verifies if the given parameter is set and is of type array. It is a helper method used to validate the type of data before performing any operations on it that require an array.

Parameters

$params

The parameter to check.

Return

bool

Returns true if the parameter is set and is an array, otherwise returns false.

61. _isNotNullAndNotEmpty

Declaration

private function _isNotNullAndNotEmpty(
    mixed $value
) : bool
{
}

Description

Check if a value is not null and not empty

Parameters

$value

The value to check

Return

bool

True if the value is not null and not empty; otherwise, false

62. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get a list of properties

Parameters

$reflectSelf

Flag indicating whether to reflect properties of the current class

$asArrayProps

Flag indicating whether to return properties as an array

Return

array

An array of property names or ReflectionProperty objects

63. listAll

Declaration

public function listAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null
) : PicoPageData
{
}

Description

List all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

64. countData

Declaration

private function countData(
    PicoDatabasePersistence $persist,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable,
    PicoSortable|string|null $sortable,
    int $findOption = 0,
    array|null $result = null
) : int
{
}

Description

Count the data based on specifications

Parameters

$persist

The persistence object

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$findOption

The find option

$result

The result set

Return

int

The count of matching records

65. findOne

Declaration

public function findOne(
    PicoSpecification|null $specification = null,
    PicoSortable|string|null $sortable = null,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record based on specifications

Parameters

$specification

The specification for filtering

$sortable

The sorting criteria

$subqueryMap

An optional map of subqueries

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

66. findAll

Declaration

public function findAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

67. findAllAsc

Declaration

public function findAllAsc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in ascending order

Return

PicoPageData

The paginated data

68. findAllDesc

Declaration

public function findAllDesc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in descending order

Return

PicoPageData

The paginated data

69. findSpecific

Declaration

public function findSpecific(
    string $selected,
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find specific records

Parameters

$selected

The selected field(s)

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

70. countAll

Declaration

public function countAll(
    PicoSpecification|null $specification = null,
    PicoPageable|null $pageable = null,
    PicoSortable|null $sortable = null
) : int|false
{
}

Description

Count all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

int|false

The count of records or false on error

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

71. findAllQuery

Declaration

public function findAllQuery(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null
) : PicoDatabaseQueryBuilder
{
}

Description

Build a query to find all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

PicoDatabaseQueryBuilder

The query builder

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

72. find

Declaration

public function find(
    mixed $params
) : self
{
}

Description

Find one record by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

73. findIfExists

Declaration

public function findIfExists(
    array $params
) : self
{
}

Description

Find one record if it exists by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance. or the current instance if not found

74. findBy

Declaration

private function findBy(
    string $method,
    mixed $params,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap,
    int $findOption
) : PicoPageData
{
}

Description

Find records by specified parameters

Parameters

$method

The method to find by

$params

The parameters for the search

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

75. countBy

Declaration

private function countBy(
    string $method,
    mixed $params
) : int
{
}

Description

Count data from the database.

Parameters

$method

The method used for finding.

$params

The parameters to use for the count.

Return

int

The count of matching records.

Throws

NoDatabaseConnectionException

If there is no database connection.

76. deleteBy

Declaration

private function deleteBy(
    string $method,
    mixed $params
) : int
{
}

Description

Delete records based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

int

The number of deleted records.

Throws

NoDatabaseConnectionException

If there is no database connection.

77. findOneWithPrimaryKeyValue

Declaration

public function findOneWithPrimaryKeyValue(
    mixed $primaryKeyVal,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record using the primary key value.

Parameters

$primaryKeyVal

The primary key value.

$subqueryMap

Optional subquery map for additional queries.

Return

self

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

78. findOneBy

Declaration

private function findOneBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

79. findOneIfExistsBy

Declaration

private function findOneIfExistsBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record if it exists based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance or the current instance if not found.

Throws

NoDatabaseConnectionException

If there is no database connection.

80. deleteOneBy

Declaration

private function deleteOneBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Delete one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

bool

True on success; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

81. existsBy

Declaration

private function existsBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Check if a record exists based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

Return

bool

True if the record exists; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

82. booleanToTextBy

Declaration

private function booleanToTextBy(
    string $propertyName,
    string[] $params
) : string
{
}

Description

Convert a boolean value to text based on the specified property name.

Parameters

$propertyName

The property name to check.

$params

The text representations for true and false.

Return

string

The corresponding text representation.

83. toArrayObject

Declaration

private function toArrayObject(
    array $result,
    bool $passive = false
) : array
{
}

Description

Convert the result to an array of objects.

Parameters

$result

The result set to convert.

$passive

Flag indicating whether the objects are passive.

Return

array

An array of objects.

84. size

Declaration

public function size() : int
{
}

Description

Get the number of properties of the object.

Return

int

The number of properties.

85. __call

Declaration

public function __call(
    string $method,
    mixed $params
) : mixed|null
{
}

Description

Magic method called when a user calls any undefined method. The __call method checks the prefix of the called method and invokes the appropriate method according to its name and parameters.

Method Descriptions:

  • hasValue: Checks if the property has a value.

    • Example: $object->hasValuePropertyName();
  • isset: Checks if the property is set.

    • Example: $object->issetPropertyName();
  • is: Retrieves the property value as a boolean.

    • Example: $isActive = $object->isActive();
  • equals: Checks if the property value equals the given value.

    • Example: $isEqual = $object->equalsPropertyName($value);
  • get: Retrieves the property value.

    • Example: $value = $object->getPropertyName();
  • set: Sets the property value.

    • Example: $object->setPropertyName($value);
  • unset: Unsets the property value.

    • Example: $object->unsetPropertyName();
  • push: Adds array elements to a property at the end.

    • Example: $object->pushPropertyName($newElement);
  • append: Appends array elements to a property at the end.

    • Example: $object->appendPropertyName($newElement);
  • unshift: Adds array elements to a property at the beginning.

    • Example: $object->unshiftPropertyName($newElement);
  • prepend: Prepends array elements to a property at the beginning.

    • Example: $object->prependPropertyName($newElement);
  • pop: Removes the last element from the property.

    • Example: $removedElement = $object->popPropertyName();
  • shift: Removes the first element from the property.

    • Example: $removedElement = $object->shiftPropertyName();
  • findOneBy: Searches for data in the database and returns one record.

    • Example: $record = $object->findOneByPropertyName($value);
    • Requires a database connection.
  • findOneIfExistsBy: Searches for data in the database by any column values and returns one record.

    • Example: $record = $object->findOneIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • deleteOneBy: Deletes data from the database by any column values and returns one record.

    • Example: $deletedRecord = $object->deleteOneByPropertyName($value, $sortable);
    • Requires a database connection.
  • findFirstBy: Searches for data in the database by any column values and returns the first record.

    • Example: $firstRecord = $object->findFirstByColumnName($value);
    • Requires a database connection.
  • findFirstIfExistsBy: Similar to findFirstBy, but returns the first record if it exists.

    • Example: $firstRecord = $object->findFirstIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findLastBy: Searches for data in the database by any column values and returns the last record.

    • Example: $lastRecord = $object->findLastByColumnName($value);
    • Requires a database connection.
  • findLastIfExistsBy: Similar to findLastBy, but returns the last record if it exists.

    • Example: $lastRecord = $object->findLastIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findBy: Searches for multiple records in the database by any column values.

    • Example: $records = $object->findByColumnName($value);
    • Requires a database connection.
  • countBy: Counts data from the database.

    • Example: $count = $object->countByColumnName();
  • existsBy: Checks for data in the database.

    • Example: $exists = $object->existsByColumn($column);
    • Requires a database connection.
  • deleteBy: Deletes data from the database without reading it first.

    • Example: $object->deleteByPropertyName($value);
    • Requires a database connection.
  • booleanToTextBy: Converts a boolean value to "yes/no" or "true/false" based on given parameters.

    • Example: $result = $object->booleanToTextByActive("Yes", "No");
    • If $obj->active is true, $result will be "Yes"; otherwise, it will be "No".
  • startsWith: Checks if the value starts with a given string.

    • Example: $startsWith = $object->startsWithPropertyName("prefix");
  • endsWith: Checks if the value ends with a given string.

    • Example: $endsWith = $object->endsWithPropertyName("suffix");
  • label: Retrieves the label associated with the given property.

    • If the label is not set, it attempts to fetch it from annotations.
    • Example: $label = $object->labelPropertyName();
  • option: Returns the first parameter if the property is set to true or equals 1; otherwise returns the second parameter.

    • Example: $option = $object->optionPropertyName("Yes", "No");
  • notNull: Checks if the specified property is set (not null).

    • Example: $isNotNull = $object->notNullPropertyName();
  • notEmpty: Checks if the specified property is set and not empty.

    • Example: $isNotEmpty = $object->notEmptyPropertyName();
  • notZero: Checks if the specified property is set and not equal to zero.

    • Example: $isNotZero = $object->notZeroPropertyName();
  • notEquals: Checks if the specified property is set and does not equal the given value.

    • Example: $isNotEqual = $object->notEqualsPropertyName($value);

Parameters

$method

Method name

$params

Parameters for the method

Return

mixed|null

The result of the called method, or null if not applicable

86. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

Return

string

A JSON representation of the object.

87. stringifyObject

Declaration

private function stringifyObject(
    self $value,
    bool $snake
) : mixed
{
}

Description

Recursively stringify an object or array of objects.

Parameters

$value

The object to stringify.

$snake

Flag to indicate whether to convert property names to snake_case.

Return

mixed

The stringified object or array.

88. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

The dump method, when supplied with an array, converts it into a friendly YAML format.

Parameters

$inline

The level at which to switch to inline YAML. If NULL, the maximum depth will be used.

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

MagicApp\Entity\AppUser

Declaration

class AppUser extends MagicObject\MagicObject { }

Package

MagicApp\Entity

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class AppUser

Represents a user in the application. The AppUser class is part of the MagicApp\Entity namespace and extends the MagicObject class, inheriting its functionalities such as serialization, deserialization, and possibly encryption/decryption.

This class can be used to model an individual user within the application, allowing for user-related properties (e.g., username, email, roles) and behaviors (e.g., authentication, authorization) to be encapsulated in a single object.

As the class currently has no properties or methods, it may serve as a basic structure that can be expanded with additional user-related attributes and methods in the future.

Constants

const MESSAGE_NO_DATABASE_CONNECTION = 'No database connection provided';
const MESSAGE_NO_RECORD_FOUND = 'No record found';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_TYPE = 'type';
const KEY_LENGTH = 'length';
const KEY_DEFAULT_VALUE = 'defaultValue';
const JSON = 'JSON';
const YAML = 'Yaml';
const ATTR_CHECKED = ' checked="checked"';
const ATTR_SELECTED = ' selected="selected"';
const FIND_OPTION_DEFAULT = 0;
const FIND_OPTION_NO_COUNT_DATA = 1;
const FIND_OPTION_NO_FETCH_DATA = 2;
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Methods

1. nullPropertyList

Declaration

public function nullPropertyList() : array
{
}

Description

Retrieves the list of null properties.

Return

array

The list of properties that are currently null.

2. __construct

Declaration

public function __construct(
    self|array|stdClass|object|null $data = null,
    PicoDatabase|PDO|null $database = null
)
{
}

Description

Constructor.

Initializes the object with the provided data and optionally connects to a database. The constructor can accept different types of data to populate the object and can also accept a PDO connection or a PicoDatabase instance to set up the database connection.

Parameters

$data

Initial data to populate the object. This can be:

$database

A database connection instance, either:

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Loads data into the object.

Parameters

$data

Data to load, which can be another MagicObject, an array, or an object.

Return

self

Returns the current instance for method chaining.

4. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

Parameters

$rawData

Raw INI data

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

5. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

Parameters

$path

File path to the INI file

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

6. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

Parameters

$rawData

YAML string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

7. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

Parameters

$path

File path to the YAML file

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

8. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

Parameters

$rawData

JSON string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

9. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Loads data from a JSON file and processes it based on the provided options.

Parameters

$path

The file path to the JSON file.

$systemEnv

Whether to replace system environment variables in the data (default: false).

$asObject

Whether to return the result as an object instead of an associative array (default: false).

$recursive

Whether to recursively convert all objects into MagicObject instances (default: false).

Return

self

Returns the current instance for method chaining.

Throws

FileNotFoundException

If the specified JSON file does not exist.

10. loadJsonData

Declaration

private function loadJsonData(
    mixed $data,
    bool $asObject,
    bool $recursive
) : self
{
}

Description

Loads processed JSON data and optionally converts it to objects or parses recursively.

Parameters

$data

The processed data to load (array or object).

$asObject

Whether to return the result as an object.

$recursive

Whether to recursively convert all objects into MagicObject instances.

Return

self

Returns the current instance for method chaining.

11. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the read-only state of the object.

When set to read-only, setters will not change the value of its properties, but loadData will still function normally.

Parameters

$readonly

Flag to set the object as read-only

Return

self

Returns the current instance for method chaining.

12. _databaseConnected

Declaration

private function _databaseConnected() : bool
{
}

Description

Check if database is connected or not

Return

bool

Returns true if the database is connected, false otherwise.

13. withDatabase

Declaration

public function withDatabase(
    PicoDatabase $database
) : self
{
}

Description

Set the database connection.

Parameters

$database

Database connection

Return

self

Returns the current instance for method chaining.

14. currentDatabase

Declaration

public function currentDatabase(
    PicoDatabase|null $database = null
) : PicoDatabase|null
{
}

Description

Set or get the current database connection.

If the parameter is not empty, set the current database to the provided value. Otherwise, return the current database or null.

Parameters

$database

Database connection

Return

PicoDatabase|null
15. databaseEntity

Declaration

public function databaseEntity(
    MagicObject|PicoDatabaseEntity|null $databaseEntity = null
) : self|PicoDatabaseEntity
{
}

Description

Set or get the database entity.

If a database entity is provided, it will be set; otherwise, the current database entity will be returned.

Parameters

$databaseEntity

The database entity to set or null to get the current entity.

Return

self|PicoDatabaseEntity

Returns the current instance for method chaining, or the current database entity if no parameter is provided.

16. removePropertyExcept

Declaration

public function removePropertyExcept(
    object|array $sourceData,
    array $propertyNames
) : object|array
{
}

Description

Remove properties except for the specified ones.

Parameters

$sourceData

Data to filter

$propertyNames

Names of properties to retain

Return

object|array

Filtered data

17. save

Declaration

public function save(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Save the current object to the database.

This method persists the current object to the database. If $includeNull is TRUE, all properties of the object, including those with null values, will be saved. If FALSE, only the properties with non-null values will be saved.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

PDOException

If a database error occurs.

18. saveQuery

Declaration

public function saveQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to save data to the database.

This method prepares a query to persist the current object to the database. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only properties with non-null values will be included.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for query construction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

19. select

Declaration

public function select() : self
{
}

Description

Select data from the database.

This method retrieves data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

20. selectAll

Declaration

public function selectAll() : self
{
}

Description

Select all data from the database.

This method retrieves all data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

21. selectQuery

Declaration

public function selectQuery() : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to select data.

This method prepares a query to select data from the database. The query can then be used to execute the retrieval of data manually if needed.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the select query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If a database error occurs.

22. executeNativeQuery

Declaration

protected function executeNativeQuery() : mixed
{
}

Description

Executes a database query based on the parameters and annotations from the caller function.

This method uses reflection to extract the query string and return type from the caller's docblock, binds the provided parameters, and executes the query against the database.

It analyzes the parameters and return type of the caller function to enable dynamic query execution tailored to the specified return type. Supported return types include:

  • void: Returns null.
  • int or integer: Returns the number of affected rows.
  • object or stdClass: Returns a single result as an object.
  • stdClass[]: Returns all results as an array of stdClass objects.
  • array: Returns all results as an associative array.
  • string: Returns the JSON-encoded results.
  • PDOStatement: Returns the prepared statement for further operations if needed.
  • MagicObject and its derived classes: If the return type is a class name or an array of class names, instances of that class will be created for each row fetched.
  • MagicObject[] and its derived classes: Instances of the corresponding class will be created for each row fetched.

Return

mixed

The result based on the return type of the caller function:

Throws

PDOException

If there is an error executing the database query.

InvalidQueryInputException

If there is no query to be executed or if the input is invalid.

InvalidReturnTypeException

If the return type specified in the docblock is invalid or unrecognized.

23. insert

Declaration

public function insert(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Insert data into the database.

This method inserts the current objectΓÇÖs data into the database. If $includeNull is TRUE, properties with null values will also be included in the insert query. If FALSE, only properties with non-null values will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be inserted. If FALSE, only non-null values will be inserted.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the insert query.

24. insertQuery

Declaration

public function insertQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for inserting data.

This method prepares a query to insert data into the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only non-null properties will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the insert query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the insert query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

25. update

Declaration

public function update(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Update data in the database.

This method updates the current object's data in the database. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only properties with non-null values will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be updated. If FALSE, only non-null values will be updated.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the update query.

26. updateQuery

Declaration

public function updateQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for updating data.

This method prepares a query to update data in the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only non-null properties will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the update query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the update query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

27. delete

Declaration

public function delete() : PDOStatement
{
}

Description

Delete data from the database.

This method deletes data associated with the current object from the database.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the delete query.

28. deleteQuery

Declaration

public function deleteQuery() : PicoDatabaseQueryBuilder
{
}

Description

Get the query for deleting data.

This method prepares a query to delete data from the database. It can be used to manually execute the query.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the delete query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

29. startTransaction

Declaration

public function startTransaction() : self
{
}

Description

Starts a database transaction.

This method begins a new database transaction. It delegates the actual transaction initiation to the transactionalCommand method, passing the "start" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error while starting the transaction.

30. commit

Declaration

public function commit() : self
{
}

Description

Commits the current database transaction.

This method commits the current transaction. If successful, it makes all database changes made during the transaction permanent. It delegates to the transactionalCommand method with the "commit" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the commit process.

31. rollback

Declaration

public function rollback() : self
{
}

Description

Rolls back the current database transaction.

This method rolls back the current transaction, undoing all database changes made during the transaction. It calls the transactionalCommand method with the "rollback" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the rollback process.

32. where

Declaration

public function where(
    PicoSpecification $specification
) : PicoDatabasePersistenceExtended
{
}

Description

Get a MagicObject with a WHERE specification.

This method applies a WHERE condition to the database query using the provided specification. The specification is an instance of PicoSpecification which defines the filtering criteria.

Parameters

$specification

The specification to define the WHERE condition.

Return

PicoDatabasePersistenceExtended

Returns an instance of PicoDatabasePersistenceExtended

Throws

NoDatabaseConnectionException

If there is no active database connection.

33. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify properties with null values.

This method tracks properties that are assigned a null value, storing them in a _nullProperties array. If a property is set to null, it is added to the _nullProperties array; if it's set to a non-null value, it is removed from the array.

Parameters

$propertyName

The name of the property to check and modify.

$propertyValue

The value to be assigned to the property.

Return

self

Returns the current instance for method chaining.

34. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Set property value.

Parameters

$propertyName

Property name

$propertyValue

Property value

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

35. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

36. append

Declaration

public function append(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property (alias for push).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

37. unshift

Declaration

public function unshift(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

38. prepend

Declaration

public function prepend(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property (alias for unshift).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

39. pop

Declaration

public function pop(
    string $propertyName
) : mixed
{
}

Description

Remove and return the last element of an array property.

This method removes the last element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the last element will be removed.

Return

mixed

The last element of the array, or null if the property is not an array or doesn't exist.

40. shift

Declaration

public function shift(
    string $propertyName
) : mixed
{
}

Description

Remove and return the first element of an array property.

This method removes the first element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the first element will be removed.

Return

mixed

The first element of the array, or null if the property is not an array or doesn't exist.

41. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get the value of a property.

This method retrieves the value of the specified property. If the property does not exist, it returns null.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property, or null if the property is not set.

42. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed|null
{
}

Description

Get the value of a property or a default value if the property is not set.

This method retrieves the value of the specified property. If the property is not set, the provided default value is returned.

Parameters

$propertyName

The name of the property to retrieve.

$defaultValue

The default value to return if the property is not set.

Return

mixed|null

The value of the property, or the default value if the property is not set.

43. __set

Declaration

public function __set(
    string $propertyName,
    mixed $propertyValue
)
{
}

Description

Set property value (magic setter).

Parameters

$propertyName

Property name

$propertyValue

Property value

44. __get

Declaration

public function __get(
    string $propertyName
) : mixed|null
{
}

Description

Magic method to get the value of a property.

This method is automatically called when an undefined or inaccessible property is accessed. It checks if the property has been set (including null values) using the __isset method and retrieves its value via the get method if it exists.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property if it is set, or null if the property is not set or accessible.

45. __isset

Declaration

public function __isset(
    string $propertyName
) : bool
{
}

Description

Magic method to check if a property is set (including null).

This method is automatically called when checking if an undefined or inaccessible property is set using isset(). It checks if the property exists and is set (even if its value is null).

Parameters

$propertyName

The name of the property to check.

Return

bool

True if the property is set (including null), false otherwise.

46. __unset

Declaration

public function __unset(
    string $propertyName
) : void
{
}

Description

Magic method to unset a property.

This method is automatically called when a property is unset using unset(). It unsets the specified property from the object.

Parameters

$propertyName

The name of the property to unset.

Return

void
47. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copy values from another object to the current instance.

This method copies property values from the provided source object to the current instance. Optionally, a filter can be applied to specify which properties to copy, and whether null values should be included.

Parameters

$source

The source object or data from which values will be copied. If a non-object is provided, this may result in unexpected behavior.

$filter

An optional array of property names to filter which properties are copied. If null, all properties are copied.

$includeNull

Flag indicating whether to include properties with null values. If false, properties with null values will be excluded from the copy.

Return

self

Returns the current instance for method chaining after copying the values.

48. removeValue

Declaration

private function removeValue(
    string $propertyName,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Remove property value and set it to null.

Parameters

$propertyName

Property name

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

49. tableInfo

Declaration

public function tableInfo() : PicoTableInfo
{
}

Description

Retrieve table information for the current instance.

This method retrieves the table information (e.g., schema, columns) associated with the current object. It lazily loads the table information, meaning it will be fetched only once and cached for future calls to improve performance.

Return

PicoTableInfo

Returns an instance of the PicoTableInfo class containing the table schema and other related metadata.

50. defaultValue

Declaration

public function defaultValue(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get default values for properties

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing default values

51. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get the object values

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing the values of the properties

52. valueObject

Declaration

public function valueObject(
    boolean|null $snakeCase = null
) : stdClass
{
}

Description

Get the object value as a specified format

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case; if null, default behavior is used

Return

stdClass

An object representing the value of the instance

53. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get the object value as an associative array

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

array

An associative array representing the object values

54. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get the object value as an associative array with the first letter of each key in upper camel case

Return

array

An associative array with keys in upper camel case

55. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if the JSON naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

56. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if the YAML naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

57. _upperCamel

Declaration

protected function _upperCamel() : bool
{
}

Description

Check if the JSON naming strategy is upper camel case

Return

bool

True if the naming strategy is upper camel case; otherwise, false

58. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if the JSON naming strategy is camel case

Return

bool

True if the naming strategy is camel case; otherwise, false

59. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

60. _isArray

Declaration

private function _isArray(
    mixed $params
) : bool
{
}

Description

Checks if the provided parameter is an array.

This function verifies if the given parameter is set and is of type array. It is a helper method used to validate the type of data before performing any operations on it that require an array.

Parameters

$params

The parameter to check.

Return

bool

Returns true if the parameter is set and is an array, otherwise returns false.

61. _isNotNullAndNotEmpty

Declaration

private function _isNotNullAndNotEmpty(
    mixed $value
) : bool
{
}

Description

Check if a value is not null and not empty

Parameters

$value

The value to check

Return

bool

True if the value is not null and not empty; otherwise, false

62. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get a list of properties

Parameters

$reflectSelf

Flag indicating whether to reflect properties of the current class

$asArrayProps

Flag indicating whether to return properties as an array

Return

array

An array of property names or ReflectionProperty objects

63. listAll

Declaration

public function listAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null
) : PicoPageData
{
}

Description

List all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

64. countData

Declaration

private function countData(
    PicoDatabasePersistence $persist,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable,
    PicoSortable|string|null $sortable,
    int $findOption = 0,
    array|null $result = null
) : int
{
}

Description

Count the data based on specifications

Parameters

$persist

The persistence object

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$findOption

The find option

$result

The result set

Return

int

The count of matching records

65. findOne

Declaration

public function findOne(
    PicoSpecification|null $specification = null,
    PicoSortable|string|null $sortable = null,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record based on specifications

Parameters

$specification

The specification for filtering

$sortable

The sorting criteria

$subqueryMap

An optional map of subqueries

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

66. findAll

Declaration

public function findAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

67. findAllAsc

Declaration

public function findAllAsc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in ascending order

Return

PicoPageData

The paginated data

68. findAllDesc

Declaration

public function findAllDesc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in descending order

Return

PicoPageData

The paginated data

69. findSpecific

Declaration

public function findSpecific(
    string $selected,
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find specific records

Parameters

$selected

The selected field(s)

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

70. countAll

Declaration

public function countAll(
    PicoSpecification|null $specification = null,
    PicoPageable|null $pageable = null,
    PicoSortable|null $sortable = null
) : int|false
{
}

Description

Count all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

int|false

The count of records or false on error

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

71. findAllQuery

Declaration

public function findAllQuery(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null
) : PicoDatabaseQueryBuilder
{
}

Description

Build a query to find all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

PicoDatabaseQueryBuilder

The query builder

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

72. find

Declaration

public function find(
    mixed $params
) : self
{
}

Description

Find one record by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

73. findIfExists

Declaration

public function findIfExists(
    array $params
) : self
{
}

Description

Find one record if it exists by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance. or the current instance if not found

74. findBy

Declaration

private function findBy(
    string $method,
    mixed $params,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap,
    int $findOption
) : PicoPageData
{
}

Description

Find records by specified parameters

Parameters

$method

The method to find by

$params

The parameters for the search

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

75. countBy

Declaration

private function countBy(
    string $method,
    mixed $params
) : int
{
}

Description

Count data from the database.

Parameters

$method

The method used for finding.

$params

The parameters to use for the count.

Return

int

The count of matching records.

Throws

NoDatabaseConnectionException

If there is no database connection.

76. deleteBy

Declaration

private function deleteBy(
    string $method,
    mixed $params
) : int
{
}

Description

Delete records based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

int

The number of deleted records.

Throws

NoDatabaseConnectionException

If there is no database connection.

77. findOneWithPrimaryKeyValue

Declaration

public function findOneWithPrimaryKeyValue(
    mixed $primaryKeyVal,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record using the primary key value.

Parameters

$primaryKeyVal

The primary key value.

$subqueryMap

Optional subquery map for additional queries.

Return

self

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

78. findOneBy

Declaration

private function findOneBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

79. findOneIfExistsBy

Declaration

private function findOneIfExistsBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record if it exists based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance or the current instance if not found.

Throws

NoDatabaseConnectionException

If there is no database connection.

80. deleteOneBy

Declaration

private function deleteOneBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Delete one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

bool

True on success; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

81. existsBy

Declaration

private function existsBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Check if a record exists based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

Return

bool

True if the record exists; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

82. booleanToTextBy

Declaration

private function booleanToTextBy(
    string $propertyName,
    string[] $params
) : string
{
}

Description

Convert a boolean value to text based on the specified property name.

Parameters

$propertyName

The property name to check.

$params

The text representations for true and false.

Return

string

The corresponding text representation.

83. toArrayObject

Declaration

private function toArrayObject(
    array $result,
    bool $passive = false
) : array
{
}

Description

Convert the result to an array of objects.

Parameters

$result

The result set to convert.

$passive

Flag indicating whether the objects are passive.

Return

array

An array of objects.

84. size

Declaration

public function size() : int
{
}

Description

Get the number of properties of the object.

Return

int

The number of properties.

85. __call

Declaration

public function __call(
    string $method,
    mixed $params
) : mixed|null
{
}

Description

Magic method called when a user calls any undefined method. The __call method checks the prefix of the called method and invokes the appropriate method according to its name and parameters.

Method Descriptions:

  • hasValue: Checks if the property has a value.

    • Example: $object->hasValuePropertyName();
  • isset: Checks if the property is set.

    • Example: $object->issetPropertyName();
  • is: Retrieves the property value as a boolean.

    • Example: $isActive = $object->isActive();
  • equals: Checks if the property value equals the given value.

    • Example: $isEqual = $object->equalsPropertyName($value);
  • get: Retrieves the property value.

    • Example: $value = $object->getPropertyName();
  • set: Sets the property value.

    • Example: $object->setPropertyName($value);
  • unset: Unsets the property value.

    • Example: $object->unsetPropertyName();
  • push: Adds array elements to a property at the end.

    • Example: $object->pushPropertyName($newElement);
  • append: Appends array elements to a property at the end.

    • Example: $object->appendPropertyName($newElement);
  • unshift: Adds array elements to a property at the beginning.

    • Example: $object->unshiftPropertyName($newElement);
  • prepend: Prepends array elements to a property at the beginning.

    • Example: $object->prependPropertyName($newElement);
  • pop: Removes the last element from the property.

    • Example: $removedElement = $object->popPropertyName();
  • shift: Removes the first element from the property.

    • Example: $removedElement = $object->shiftPropertyName();
  • findOneBy: Searches for data in the database and returns one record.

    • Example: $record = $object->findOneByPropertyName($value);
    • Requires a database connection.
  • findOneIfExistsBy: Searches for data in the database by any column values and returns one record.

    • Example: $record = $object->findOneIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • deleteOneBy: Deletes data from the database by any column values and returns one record.

    • Example: $deletedRecord = $object->deleteOneByPropertyName($value, $sortable);
    • Requires a database connection.
  • findFirstBy: Searches for data in the database by any column values and returns the first record.

    • Example: $firstRecord = $object->findFirstByColumnName($value);
    • Requires a database connection.
  • findFirstIfExistsBy: Similar to findFirstBy, but returns the first record if it exists.

    • Example: $firstRecord = $object->findFirstIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findLastBy: Searches for data in the database by any column values and returns the last record.

    • Example: $lastRecord = $object->findLastByColumnName($value);
    • Requires a database connection.
  • findLastIfExistsBy: Similar to findLastBy, but returns the last record if it exists.

    • Example: $lastRecord = $object->findLastIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findBy: Searches for multiple records in the database by any column values.

    • Example: $records = $object->findByColumnName($value);
    • Requires a database connection.
  • countBy: Counts data from the database.

    • Example: $count = $object->countByColumnName();
  • existsBy: Checks for data in the database.

    • Example: $exists = $object->existsByColumn($column);
    • Requires a database connection.
  • deleteBy: Deletes data from the database without reading it first.

    • Example: $object->deleteByPropertyName($value);
    • Requires a database connection.
  • booleanToTextBy: Converts a boolean value to "yes/no" or "true/false" based on given parameters.

    • Example: $result = $object->booleanToTextByActive("Yes", "No");
    • If $obj->active is true, $result will be "Yes"; otherwise, it will be "No".
  • startsWith: Checks if the value starts with a given string.

    • Example: $startsWith = $object->startsWithPropertyName("prefix");
  • endsWith: Checks if the value ends with a given string.

    • Example: $endsWith = $object->endsWithPropertyName("suffix");
  • label: Retrieves the label associated with the given property.

    • If the label is not set, it attempts to fetch it from annotations.
    • Example: $label = $object->labelPropertyName();
  • option: Returns the first parameter if the property is set to true or equals 1; otherwise returns the second parameter.

    • Example: $option = $object->optionPropertyName("Yes", "No");
  • notNull: Checks if the specified property is set (not null).

    • Example: $isNotNull = $object->notNullPropertyName();
  • notEmpty: Checks if the specified property is set and not empty.

    • Example: $isNotEmpty = $object->notEmptyPropertyName();
  • notZero: Checks if the specified property is set and not equal to zero.

    • Example: $isNotZero = $object->notZeroPropertyName();
  • notEquals: Checks if the specified property is set and does not equal the given value.

    • Example: $isNotEqual = $object->notEqualsPropertyName($value);

Parameters

$method

Method name

$params

Parameters for the method

Return

mixed|null

The result of the called method, or null if not applicable

86. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

Return

string

A JSON representation of the object.

87. stringifyObject

Declaration

private function stringifyObject(
    self $value,
    bool $snake
) : mixed
{
}

Description

Recursively stringify an object or array of objects.

Parameters

$value

The object to stringify.

$snake

Flag to indicate whether to convert property names to snake_case.

Return

mixed

The stringified object or array.

88. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

The dump method, when supplied with an array, converts it into a friendly YAML format.

Parameters

$inline

The level at which to switch to inline YAML. If NULL, the maximum depth will be used.

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

MagicApp\Entity\AppUserLevel

Declaration

class AppUserLevel extends MagicObject\MagicObject { }

Package

MagicApp\Entity

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class AppUserLevel

Represents a user level or role within the application. The AppUserLevel class is part of the MagicApp\Entity namespace and extends the MagicObject class, inheriting functionalities such as serialization, deserialization, and potentially encryption/decryption.

The AppUserLevel class is used to define different levels or roles assigned to users within the application. These roles can determine user permissions, access control, and other user-specific behavior based on their assigned level.

Although the class currently does not contain any properties or methods, it can be expanded in the future to include attributes such as role names, permissions, descriptions, or any other relevant data tied to user roles.

Constants

const MESSAGE_NO_DATABASE_CONNECTION = 'No database connection provided';
const MESSAGE_NO_RECORD_FOUND = 'No record found';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_TYPE = 'type';
const KEY_LENGTH = 'length';
const KEY_DEFAULT_VALUE = 'defaultValue';
const JSON = 'JSON';
const YAML = 'Yaml';
const ATTR_CHECKED = ' checked="checked"';
const ATTR_SELECTED = ' selected="selected"';
const FIND_OPTION_DEFAULT = 0;
const FIND_OPTION_NO_COUNT_DATA = 1;
const FIND_OPTION_NO_FETCH_DATA = 2;
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Methods

1. nullPropertyList

Declaration

public function nullPropertyList() : array
{
}

Description

Retrieves the list of null properties.

Return

array

The list of properties that are currently null.

2. __construct

Declaration

public function __construct(
    self|array|stdClass|object|null $data = null,
    PicoDatabase|PDO|null $database = null
)
{
}

Description

Constructor.

Initializes the object with the provided data and optionally connects to a database. The constructor can accept different types of data to populate the object and can also accept a PDO connection or a PicoDatabase instance to set up the database connection.

Parameters

$data

Initial data to populate the object. This can be:

$database

A database connection instance, either:

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Loads data into the object.

Parameters

$data

Data to load, which can be another MagicObject, an array, or an object.

Return

self

Returns the current instance for method chaining.

4. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

Parameters

$rawData

Raw INI data

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

5. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

Parameters

$path

File path to the INI file

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

6. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

Parameters

$rawData

YAML string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

7. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

Parameters

$path

File path to the YAML file

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

8. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

Parameters

$rawData

JSON string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

9. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Loads data from a JSON file and processes it based on the provided options.

Parameters

$path

The file path to the JSON file.

$systemEnv

Whether to replace system environment variables in the data (default: false).

$asObject

Whether to return the result as an object instead of an associative array (default: false).

$recursive

Whether to recursively convert all objects into MagicObject instances (default: false).

Return

self

Returns the current instance for method chaining.

Throws

FileNotFoundException

If the specified JSON file does not exist.

10. loadJsonData

Declaration

private function loadJsonData(
    mixed $data,
    bool $asObject,
    bool $recursive
) : self
{
}

Description

Loads processed JSON data and optionally converts it to objects or parses recursively.

Parameters

$data

The processed data to load (array or object).

$asObject

Whether to return the result as an object.

$recursive

Whether to recursively convert all objects into MagicObject instances.

Return

self

Returns the current instance for method chaining.

11. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the read-only state of the object.

When set to read-only, setters will not change the value of its properties, but loadData will still function normally.

Parameters

$readonly

Flag to set the object as read-only

Return

self

Returns the current instance for method chaining.

12. _databaseConnected

Declaration

private function _databaseConnected() : bool
{
}

Description

Check if database is connected or not

Return

bool

Returns true if the database is connected, false otherwise.

13. withDatabase

Declaration

public function withDatabase(
    PicoDatabase $database
) : self
{
}

Description

Set the database connection.

Parameters

$database

Database connection

Return

self

Returns the current instance for method chaining.

14. currentDatabase

Declaration

public function currentDatabase(
    PicoDatabase|null $database = null
) : PicoDatabase|null
{
}

Description

Set or get the current database connection.

If the parameter is not empty, set the current database to the provided value. Otherwise, return the current database or null.

Parameters

$database

Database connection

Return

PicoDatabase|null
15. databaseEntity

Declaration

public function databaseEntity(
    MagicObject|PicoDatabaseEntity|null $databaseEntity = null
) : self|PicoDatabaseEntity
{
}

Description

Set or get the database entity.

If a database entity is provided, it will be set; otherwise, the current database entity will be returned.

Parameters

$databaseEntity

The database entity to set or null to get the current entity.

Return

self|PicoDatabaseEntity

Returns the current instance for method chaining, or the current database entity if no parameter is provided.

16. removePropertyExcept

Declaration

public function removePropertyExcept(
    object|array $sourceData,
    array $propertyNames
) : object|array
{
}

Description

Remove properties except for the specified ones.

Parameters

$sourceData

Data to filter

$propertyNames

Names of properties to retain

Return

object|array

Filtered data

17. save

Declaration

public function save(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Save the current object to the database.

This method persists the current object to the database. If $includeNull is TRUE, all properties of the object, including those with null values, will be saved. If FALSE, only the properties with non-null values will be saved.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

PDOException

If a database error occurs.

18. saveQuery

Declaration

public function saveQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to save data to the database.

This method prepares a query to persist the current object to the database. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only properties with non-null values will be included.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for query construction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

19. select

Declaration

public function select() : self
{
}

Description

Select data from the database.

This method retrieves data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

20. selectAll

Declaration

public function selectAll() : self
{
}

Description

Select all data from the database.

This method retrieves all data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

21. selectQuery

Declaration

public function selectQuery() : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to select data.

This method prepares a query to select data from the database. The query can then be used to execute the retrieval of data manually if needed.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the select query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If a database error occurs.

22. executeNativeQuery

Declaration

protected function executeNativeQuery() : mixed
{
}

Description

Executes a database query based on the parameters and annotations from the caller function.

This method uses reflection to extract the query string and return type from the caller's docblock, binds the provided parameters, and executes the query against the database.

It analyzes the parameters and return type of the caller function to enable dynamic query execution tailored to the specified return type. Supported return types include:

  • void: Returns null.
  • int or integer: Returns the number of affected rows.
  • object or stdClass: Returns a single result as an object.
  • stdClass[]: Returns all results as an array of stdClass objects.
  • array: Returns all results as an associative array.
  • string: Returns the JSON-encoded results.
  • PDOStatement: Returns the prepared statement for further operations if needed.
  • MagicObject and its derived classes: If the return type is a class name or an array of class names, instances of that class will be created for each row fetched.
  • MagicObject[] and its derived classes: Instances of the corresponding class will be created for each row fetched.

Return

mixed

The result based on the return type of the caller function:

Throws

PDOException

If there is an error executing the database query.

InvalidQueryInputException

If there is no query to be executed or if the input is invalid.

InvalidReturnTypeException

If the return type specified in the docblock is invalid or unrecognized.

23. insert

Declaration

public function insert(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Insert data into the database.

This method inserts the current objectΓÇÖs data into the database. If $includeNull is TRUE, properties with null values will also be included in the insert query. If FALSE, only properties with non-null values will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be inserted. If FALSE, only non-null values will be inserted.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the insert query.

24. insertQuery

Declaration

public function insertQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for inserting data.

This method prepares a query to insert data into the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only non-null properties will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the insert query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the insert query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

25. update

Declaration

public function update(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Update data in the database.

This method updates the current object's data in the database. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only properties with non-null values will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be updated. If FALSE, only non-null values will be updated.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the update query.

26. updateQuery

Declaration

public function updateQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for updating data.

This method prepares a query to update data in the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only non-null properties will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the update query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the update query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

27. delete

Declaration

public function delete() : PDOStatement
{
}

Description

Delete data from the database.

This method deletes data associated with the current object from the database.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the delete query.

28. deleteQuery

Declaration

public function deleteQuery() : PicoDatabaseQueryBuilder
{
}

Description

Get the query for deleting data.

This method prepares a query to delete data from the database. It can be used to manually execute the query.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the delete query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

29. startTransaction

Declaration

public function startTransaction() : self
{
}

Description

Starts a database transaction.

This method begins a new database transaction. It delegates the actual transaction initiation to the transactionalCommand method, passing the "start" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error while starting the transaction.

30. commit

Declaration

public function commit() : self
{
}

Description

Commits the current database transaction.

This method commits the current transaction. If successful, it makes all database changes made during the transaction permanent. It delegates to the transactionalCommand method with the "commit" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the commit process.

31. rollback

Declaration

public function rollback() : self
{
}

Description

Rolls back the current database transaction.

This method rolls back the current transaction, undoing all database changes made during the transaction. It calls the transactionalCommand method with the "rollback" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the rollback process.

32. where

Declaration

public function where(
    PicoSpecification $specification
) : PicoDatabasePersistenceExtended
{
}

Description

Get a MagicObject with a WHERE specification.

This method applies a WHERE condition to the database query using the provided specification. The specification is an instance of PicoSpecification which defines the filtering criteria.

Parameters

$specification

The specification to define the WHERE condition.

Return

PicoDatabasePersistenceExtended

Returns an instance of PicoDatabasePersistenceExtended

Throws

NoDatabaseConnectionException

If there is no active database connection.

33. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify properties with null values.

This method tracks properties that are assigned a null value, storing them in a _nullProperties array. If a property is set to null, it is added to the _nullProperties array; if it's set to a non-null value, it is removed from the array.

Parameters

$propertyName

The name of the property to check and modify.

$propertyValue

The value to be assigned to the property.

Return

self

Returns the current instance for method chaining.

34. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Set property value.

Parameters

$propertyName

Property name

$propertyValue

Property value

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

35. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

36. append

Declaration

public function append(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property (alias for push).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

37. unshift

Declaration

public function unshift(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

38. prepend

Declaration

public function prepend(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property (alias for unshift).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

39. pop

Declaration

public function pop(
    string $propertyName
) : mixed
{
}

Description

Remove and return the last element of an array property.

This method removes the last element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the last element will be removed.

Return

mixed

The last element of the array, or null if the property is not an array or doesn't exist.

40. shift

Declaration

public function shift(
    string $propertyName
) : mixed
{
}

Description

Remove and return the first element of an array property.

This method removes the first element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the first element will be removed.

Return

mixed

The first element of the array, or null if the property is not an array or doesn't exist.

41. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get the value of a property.

This method retrieves the value of the specified property. If the property does not exist, it returns null.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property, or null if the property is not set.

42. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed|null
{
}

Description

Get the value of a property or a default value if the property is not set.

This method retrieves the value of the specified property. If the property is not set, the provided default value is returned.

Parameters

$propertyName

The name of the property to retrieve.

$defaultValue

The default value to return if the property is not set.

Return

mixed|null

The value of the property, or the default value if the property is not set.

43. __set

Declaration

public function __set(
    string $propertyName,
    mixed $propertyValue
)
{
}

Description

Set property value (magic setter).

Parameters

$propertyName

Property name

$propertyValue

Property value

44. __get

Declaration

public function __get(
    string $propertyName
) : mixed|null
{
}

Description

Magic method to get the value of a property.

This method is automatically called when an undefined or inaccessible property is accessed. It checks if the property has been set (including null values) using the __isset method and retrieves its value via the get method if it exists.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property if it is set, or null if the property is not set or accessible.

45. __isset

Declaration

public function __isset(
    string $propertyName
) : bool
{
}

Description

Magic method to check if a property is set (including null).

This method is automatically called when checking if an undefined or inaccessible property is set using isset(). It checks if the property exists and is set (even if its value is null).

Parameters

$propertyName

The name of the property to check.

Return

bool

True if the property is set (including null), false otherwise.

46. __unset

Declaration

public function __unset(
    string $propertyName
) : void
{
}

Description

Magic method to unset a property.

This method is automatically called when a property is unset using unset(). It unsets the specified property from the object.

Parameters

$propertyName

The name of the property to unset.

Return

void
47. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copy values from another object to the current instance.

This method copies property values from the provided source object to the current instance. Optionally, a filter can be applied to specify which properties to copy, and whether null values should be included.

Parameters

$source

The source object or data from which values will be copied. If a non-object is provided, this may result in unexpected behavior.

$filter

An optional array of property names to filter which properties are copied. If null, all properties are copied.

$includeNull

Flag indicating whether to include properties with null values. If false, properties with null values will be excluded from the copy.

Return

self

Returns the current instance for method chaining after copying the values.

48. removeValue

Declaration

private function removeValue(
    string $propertyName,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Remove property value and set it to null.

Parameters

$propertyName

Property name

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

49. tableInfo

Declaration

public function tableInfo() : PicoTableInfo
{
}

Description

Retrieve table information for the current instance.

This method retrieves the table information (e.g., schema, columns) associated with the current object. It lazily loads the table information, meaning it will be fetched only once and cached for future calls to improve performance.

Return

PicoTableInfo

Returns an instance of the PicoTableInfo class containing the table schema and other related metadata.

50. defaultValue

Declaration

public function defaultValue(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get default values for properties

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing default values

51. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get the object values

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing the values of the properties

52. valueObject

Declaration

public function valueObject(
    boolean|null $snakeCase = null
) : stdClass
{
}

Description

Get the object value as a specified format

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case; if null, default behavior is used

Return

stdClass

An object representing the value of the instance

53. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get the object value as an associative array

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

array

An associative array representing the object values

54. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get the object value as an associative array with the first letter of each key in upper camel case

Return

array

An associative array with keys in upper camel case

55. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if the JSON naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

56. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if the YAML naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

57. _upperCamel

Declaration

protected function _upperCamel() : bool
{
}

Description

Check if the JSON naming strategy is upper camel case

Return

bool

True if the naming strategy is upper camel case; otherwise, false

58. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if the JSON naming strategy is camel case

Return

bool

True if the naming strategy is camel case; otherwise, false

59. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

60. _isArray

Declaration

private function _isArray(
    mixed $params
) : bool
{
}

Description

Checks if the provided parameter is an array.

This function verifies if the given parameter is set and is of type array. It is a helper method used to validate the type of data before performing any operations on it that require an array.

Parameters

$params

The parameter to check.

Return

bool

Returns true if the parameter is set and is an array, otherwise returns false.

61. _isNotNullAndNotEmpty

Declaration

private function _isNotNullAndNotEmpty(
    mixed $value
) : bool
{
}

Description

Check if a value is not null and not empty

Parameters

$value

The value to check

Return

bool

True if the value is not null and not empty; otherwise, false

62. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get a list of properties

Parameters

$reflectSelf

Flag indicating whether to reflect properties of the current class

$asArrayProps

Flag indicating whether to return properties as an array

Return

array

An array of property names or ReflectionProperty objects

63. listAll

Declaration

public function listAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null
) : PicoPageData
{
}

Description

List all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

64. countData

Declaration

private function countData(
    PicoDatabasePersistence $persist,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable,
    PicoSortable|string|null $sortable,
    int $findOption = 0,
    array|null $result = null
) : int
{
}

Description

Count the data based on specifications

Parameters

$persist

The persistence object

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$findOption

The find option

$result

The result set

Return

int

The count of matching records

65. findOne

Declaration

public function findOne(
    PicoSpecification|null $specification = null,
    PicoSortable|string|null $sortable = null,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record based on specifications

Parameters

$specification

The specification for filtering

$sortable

The sorting criteria

$subqueryMap

An optional map of subqueries

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

66. findAll

Declaration

public function findAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

67. findAllAsc

Declaration

public function findAllAsc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in ascending order

Return

PicoPageData

The paginated data

68. findAllDesc

Declaration

public function findAllDesc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in descending order

Return

PicoPageData

The paginated data

69. findSpecific

Declaration

public function findSpecific(
    string $selected,
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find specific records

Parameters

$selected

The selected field(s)

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

70. countAll

Declaration

public function countAll(
    PicoSpecification|null $specification = null,
    PicoPageable|null $pageable = null,
    PicoSortable|null $sortable = null
) : int|false
{
}

Description

Count all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

int|false

The count of records or false on error

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

71. findAllQuery

Declaration

public function findAllQuery(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null
) : PicoDatabaseQueryBuilder
{
}

Description

Build a query to find all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

PicoDatabaseQueryBuilder

The query builder

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

72. find

Declaration

public function find(
    mixed $params
) : self
{
}

Description

Find one record by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

73. findIfExists

Declaration

public function findIfExists(
    array $params
) : self
{
}

Description

Find one record if it exists by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance. or the current instance if not found

74. findBy

Declaration

private function findBy(
    string $method,
    mixed $params,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap,
    int $findOption
) : PicoPageData
{
}

Description

Find records by specified parameters

Parameters

$method

The method to find by

$params

The parameters for the search

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

75. countBy

Declaration

private function countBy(
    string $method,
    mixed $params
) : int
{
}

Description

Count data from the database.

Parameters

$method

The method used for finding.

$params

The parameters to use for the count.

Return

int

The count of matching records.

Throws

NoDatabaseConnectionException

If there is no database connection.

76. deleteBy

Declaration

private function deleteBy(
    string $method,
    mixed $params
) : int
{
}

Description

Delete records based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

int

The number of deleted records.

Throws

NoDatabaseConnectionException

If there is no database connection.

77. findOneWithPrimaryKeyValue

Declaration

public function findOneWithPrimaryKeyValue(
    mixed $primaryKeyVal,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record using the primary key value.

Parameters

$primaryKeyVal

The primary key value.

$subqueryMap

Optional subquery map for additional queries.

Return

self

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

78. findOneBy

Declaration

private function findOneBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

79. findOneIfExistsBy

Declaration

private function findOneIfExistsBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record if it exists based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance or the current instance if not found.

Throws

NoDatabaseConnectionException

If there is no database connection.

80. deleteOneBy

Declaration

private function deleteOneBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Delete one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

bool

True on success; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

81. existsBy

Declaration

private function existsBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Check if a record exists based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

Return

bool

True if the record exists; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

82. booleanToTextBy

Declaration

private function booleanToTextBy(
    string $propertyName,
    string[] $params
) : string
{
}

Description

Convert a boolean value to text based on the specified property name.

Parameters

$propertyName

The property name to check.

$params

The text representations for true and false.

Return

string

The corresponding text representation.

83. toArrayObject

Declaration

private function toArrayObject(
    array $result,
    bool $passive = false
) : array
{
}

Description

Convert the result to an array of objects.

Parameters

$result

The result set to convert.

$passive

Flag indicating whether the objects are passive.

Return

array

An array of objects.

84. size

Declaration

public function size() : int
{
}

Description

Get the number of properties of the object.

Return

int

The number of properties.

85. __call

Declaration

public function __call(
    string $method,
    mixed $params
) : mixed|null
{
}

Description

Magic method called when a user calls any undefined method. The __call method checks the prefix of the called method and invokes the appropriate method according to its name and parameters.

Method Descriptions:

  • hasValue: Checks if the property has a value.

    • Example: $object->hasValuePropertyName();
  • isset: Checks if the property is set.

    • Example: $object->issetPropertyName();
  • is: Retrieves the property value as a boolean.

    • Example: $isActive = $object->isActive();
  • equals: Checks if the property value equals the given value.

    • Example: $isEqual = $object->equalsPropertyName($value);
  • get: Retrieves the property value.

    • Example: $value = $object->getPropertyName();
  • set: Sets the property value.

    • Example: $object->setPropertyName($value);
  • unset: Unsets the property value.

    • Example: $object->unsetPropertyName();
  • push: Adds array elements to a property at the end.

    • Example: $object->pushPropertyName($newElement);
  • append: Appends array elements to a property at the end.

    • Example: $object->appendPropertyName($newElement);
  • unshift: Adds array elements to a property at the beginning.

    • Example: $object->unshiftPropertyName($newElement);
  • prepend: Prepends array elements to a property at the beginning.

    • Example: $object->prependPropertyName($newElement);
  • pop: Removes the last element from the property.

    • Example: $removedElement = $object->popPropertyName();
  • shift: Removes the first element from the property.

    • Example: $removedElement = $object->shiftPropertyName();
  • findOneBy: Searches for data in the database and returns one record.

    • Example: $record = $object->findOneByPropertyName($value);
    • Requires a database connection.
  • findOneIfExistsBy: Searches for data in the database by any column values and returns one record.

    • Example: $record = $object->findOneIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • deleteOneBy: Deletes data from the database by any column values and returns one record.

    • Example: $deletedRecord = $object->deleteOneByPropertyName($value, $sortable);
    • Requires a database connection.
  • findFirstBy: Searches for data in the database by any column values and returns the first record.

    • Example: $firstRecord = $object->findFirstByColumnName($value);
    • Requires a database connection.
  • findFirstIfExistsBy: Similar to findFirstBy, but returns the first record if it exists.

    • Example: $firstRecord = $object->findFirstIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findLastBy: Searches for data in the database by any column values and returns the last record.

    • Example: $lastRecord = $object->findLastByColumnName($value);
    • Requires a database connection.
  • findLastIfExistsBy: Similar to findLastBy, but returns the last record if it exists.

    • Example: $lastRecord = $object->findLastIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findBy: Searches for multiple records in the database by any column values.

    • Example: $records = $object->findByColumnName($value);
    • Requires a database connection.
  • countBy: Counts data from the database.

    • Example: $count = $object->countByColumnName();
  • existsBy: Checks for data in the database.

    • Example: $exists = $object->existsByColumn($column);
    • Requires a database connection.
  • deleteBy: Deletes data from the database without reading it first.

    • Example: $object->deleteByPropertyName($value);
    • Requires a database connection.
  • booleanToTextBy: Converts a boolean value to "yes/no" or "true/false" based on given parameters.

    • Example: $result = $object->booleanToTextByActive("Yes", "No");
    • If $obj->active is true, $result will be "Yes"; otherwise, it will be "No".
  • startsWith: Checks if the value starts with a given string.

    • Example: $startsWith = $object->startsWithPropertyName("prefix");
  • endsWith: Checks if the value ends with a given string.

    • Example: $endsWith = $object->endsWithPropertyName("suffix");
  • label: Retrieves the label associated with the given property.

    • If the label is not set, it attempts to fetch it from annotations.
    • Example: $label = $object->labelPropertyName();
  • option: Returns the first parameter if the property is set to true or equals 1; otherwise returns the second parameter.

    • Example: $option = $object->optionPropertyName("Yes", "No");
  • notNull: Checks if the specified property is set (not null).

    • Example: $isNotNull = $object->notNullPropertyName();
  • notEmpty: Checks if the specified property is set and not empty.

    • Example: $isNotEmpty = $object->notEmptyPropertyName();
  • notZero: Checks if the specified property is set and not equal to zero.

    • Example: $isNotZero = $object->notZeroPropertyName();
  • notEquals: Checks if the specified property is set and does not equal the given value.

    • Example: $isNotEqual = $object->notEqualsPropertyName($value);

Parameters

$method

Method name

$params

Parameters for the method

Return

mixed|null

The result of the called method, or null if not applicable

86. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

Return

string

A JSON representation of the object.

87. stringifyObject

Declaration

private function stringifyObject(
    self $value,
    bool $snake
) : mixed
{
}

Description

Recursively stringify an object or array of objects.

Parameters

$value

The object to stringify.

$snake

Flag to indicate whether to convert property names to snake_case.

Return

mixed

The stringified object or array.

88. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

The dump method, when supplied with an array, converts it into a friendly YAML format.

Parameters

$inline

The level at which to switch to inline YAML. If NULL, the maximum depth will be used.

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

MagicApp\Entity\AppUserRole

Declaration

class AppUserRole extends MagicObject\MagicObject { }

Package

MagicApp\Entity

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class AppUserRole

Represents a user role within the application. The AppUserRole class is part of the MagicApp\Entity namespace and extends the MagicObject class, which provides core functionalities such as serialization, deserialization, and possibly encryption/decryption depending on the parent class implementation.

The AppUserRole class is intended to define and manage roles that can be assigned to users within the application. These roles will typically be used to grant or restrict access to certain resources or operations based on the assigned role. Roles can correspond to specific sets of permissions or privileges.

While the class does not currently have any properties or methods, it can be extended in the future to include attributes such as role name, description, permissions, and any other relevant data associated with user roles.

Constants

const MESSAGE_NO_DATABASE_CONNECTION = 'No database connection provided';
const MESSAGE_NO_RECORD_FOUND = 'No record found';
const PROPERTY_NAMING_STRATEGY = 'property-naming-strategy';
const PROPERTY_NAMING_STRATEGY_CAMEL = 'propertyNamingStrategy';
const KEY_PROPERTY_TYPE = 'propertyType';
const KEY_NAME = 'name';
const KEY_VALUE = 'value';
const KEY_TYPE = 'type';
const KEY_LENGTH = 'length';
const KEY_DEFAULT_VALUE = 'defaultValue';
const JSON = 'JSON';
const YAML = 'Yaml';
const ATTR_CHECKED = ' checked="checked"';
const ATTR_SELECTED = ' selected="selected"';
const FIND_OPTION_DEFAULT = 0;
const FIND_OPTION_NO_COUNT_DATA = 1;
const FIND_OPTION_NO_FETCH_DATA = 2;
const SNAKE_CASE = 'SNAKE_CASE';
const UPPER_CAMEL_CASE = 'UPPER_CAMEL_CASE';

Methods

1. nullPropertyList

Declaration

public function nullPropertyList() : array
{
}

Description

Retrieves the list of null properties.

Return

array

The list of properties that are currently null.

2. __construct

Declaration

public function __construct(
    self|array|stdClass|object|null $data = null,
    PicoDatabase|PDO|null $database = null
)
{
}

Description

Constructor.

Initializes the object with the provided data and optionally connects to a database. The constructor can accept different types of data to populate the object and can also accept a PDO connection or a PicoDatabase instance to set up the database connection.

Parameters

$data

Initial data to populate the object. This can be:

$database

A database connection instance, either:

Throws

InvalidAnnotationException

If the annotations are invalid or cannot be parsed.

3. loadData

Declaration

public function loadData(
    mixed $data
) : self
{
}

Description

Loads data into the object.

Parameters

$data

Data to load, which can be another MagicObject, an array, or an object.

Return

self

Returns the current instance for method chaining.

4. loadIniString

Declaration

public function loadIniString(
    string $rawData,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI string.

Parameters

$rawData

Raw INI data

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

5. loadIniFile

Declaration

public function loadIniFile(
    string $path,
    bool $systemEnv = false
) : self
{
}

Description

Load data from an INI file.

Parameters

$path

File path to the INI file

$systemEnv

Flag to indicate whether to use environment variables

Return

self

Returns the current instance for method chaining.

6. loadYamlString

Declaration

public function loadYamlString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML string.

Parameters

$rawData

YAML string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

7. loadYamlFile

Declaration

public function loadYamlFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a YAML file.

Parameters

$path

File path to the YAML file

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

8. loadJsonString

Declaration

public function loadJsonString(
    string $rawData,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Load data from a JSON string.

Parameters

$rawData

JSON string

$systemEnv

Replace all environment variable values

$asObject

Result as an object instead of an array

$recursive

Convert all objects to MagicObject

Return

self

Returns the current instance for method chaining.

9. loadJsonFile

Declaration

public function loadJsonFile(
    string $path,
    bool $systemEnv = false,
    bool $asObject = false,
    bool $recursive = false
) : self
{
}

Description

Loads data from a JSON file and processes it based on the provided options.

Parameters

$path

The file path to the JSON file.

$systemEnv

Whether to replace system environment variables in the data (default: false).

$asObject

Whether to return the result as an object instead of an associative array (default: false).

$recursive

Whether to recursively convert all objects into MagicObject instances (default: false).

Return

self

Returns the current instance for method chaining.

Throws

FileNotFoundException

If the specified JSON file does not exist.

10. loadJsonData

Declaration

private function loadJsonData(
    mixed $data,
    bool $asObject,
    bool $recursive
) : self
{
}

Description

Loads processed JSON data and optionally converts it to objects or parses recursively.

Parameters

$data

The processed data to load (array or object).

$asObject

Whether to return the result as an object.

$recursive

Whether to recursively convert all objects into MagicObject instances.

Return

self

Returns the current instance for method chaining.

11. readOnly

Declaration

protected function readOnly(
    bool $readonly
) : self
{
}

Description

Set the read-only state of the object.

When set to read-only, setters will not change the value of its properties, but loadData will still function normally.

Parameters

$readonly

Flag to set the object as read-only

Return

self

Returns the current instance for method chaining.

12. _databaseConnected

Declaration

private function _databaseConnected() : bool
{
}

Description

Check if database is connected or not

Return

bool

Returns true if the database is connected, false otherwise.

13. withDatabase

Declaration

public function withDatabase(
    PicoDatabase $database
) : self
{
}

Description

Set the database connection.

Parameters

$database

Database connection

Return

self

Returns the current instance for method chaining.

14. currentDatabase

Declaration

public function currentDatabase(
    PicoDatabase|null $database = null
) : PicoDatabase|null
{
}

Description

Set or get the current database connection.

If the parameter is not empty, set the current database to the provided value. Otherwise, return the current database or null.

Parameters

$database

Database connection

Return

PicoDatabase|null
15. databaseEntity

Declaration

public function databaseEntity(
    MagicObject|PicoDatabaseEntity|null $databaseEntity = null
) : self|PicoDatabaseEntity
{
}

Description

Set or get the database entity.

If a database entity is provided, it will be set; otherwise, the current database entity will be returned.

Parameters

$databaseEntity

The database entity to set or null to get the current entity.

Return

self|PicoDatabaseEntity

Returns the current instance for method chaining, or the current database entity if no parameter is provided.

16. removePropertyExcept

Declaration

public function removePropertyExcept(
    object|array $sourceData,
    array $propertyNames
) : object|array
{
}

Description

Remove properties except for the specified ones.

Parameters

$sourceData

Data to filter

$propertyNames

Names of properties to retain

Return

object|array

Filtered data

17. save

Declaration

public function save(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Save the current object to the database.

This method persists the current object to the database. If $includeNull is TRUE, all properties of the object, including those with null values, will be saved. If FALSE, only the properties with non-null values will be saved.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

PDOException

If a database error occurs.

18. saveQuery

Declaration

public function saveQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to save data to the database.

This method prepares a query to persist the current object to the database. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only properties with non-null values will be included.

Parameters

$includeNull

If TRUE, all properties, including null, will be saved.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for query construction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no corresponding record is found.

19. select

Declaration

public function select() : self
{
}

Description

Select data from the database.

This method retrieves data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

20. selectAll

Declaration

public function selectAll() : self
{
}

Description

Select all data from the database.

This method retrieves all data from the database. If no data is found, a NoRecordFoundException will be thrown. The retrieved data is then loaded into the current instance for further use.

Return

self

Returns the current instance for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

NoRecordFoundException

If no records are found in the database.

PDOException

If a database error occurs.

21. selectQuery

Declaration

public function selectQuery() : PicoDatabaseQueryBuilder
{
}

Description

Generate a query to select data.

This method prepares a query to select data from the database. The query can then be used to execute the retrieval of data manually if needed.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the select query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If a database error occurs.

22. executeNativeQuery

Declaration

protected function executeNativeQuery() : mixed
{
}

Description

Executes a database query based on the parameters and annotations from the caller function.

This method uses reflection to extract the query string and return type from the caller's docblock, binds the provided parameters, and executes the query against the database.

It analyzes the parameters and return type of the caller function to enable dynamic query execution tailored to the specified return type. Supported return types include:

  • void: Returns null.
  • int or integer: Returns the number of affected rows.
  • object or stdClass: Returns a single result as an object.
  • stdClass[]: Returns all results as an array of stdClass objects.
  • array: Returns all results as an associative array.
  • string: Returns the JSON-encoded results.
  • PDOStatement: Returns the prepared statement for further operations if needed.
  • MagicObject and its derived classes: If the return type is a class name or an array of class names, instances of that class will be created for each row fetched.
  • MagicObject[] and its derived classes: Instances of the corresponding class will be created for each row fetched.

Return

mixed

The result based on the return type of the caller function:

Throws

PDOException

If there is an error executing the database query.

InvalidQueryInputException

If there is no query to be executed or if the input is invalid.

InvalidReturnTypeException

If the return type specified in the docblock is invalid or unrecognized.

23. insert

Declaration

public function insert(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Insert data into the database.

This method inserts the current objectΓÇÖs data into the database. If $includeNull is TRUE, properties with null values will also be included in the insert query. If FALSE, only properties with non-null values will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be inserted. If FALSE, only non-null values will be inserted.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the insert query.

24. insertQuery

Declaration

public function insertQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for inserting data.

This method prepares a query to insert data into the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the query. If FALSE, only non-null properties will be inserted.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the insert query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the insert query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

25. update

Declaration

public function update(
    bool $includeNull = false
) : PDOStatement
{
}

Description

Update data in the database.

This method updates the current object's data in the database. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only properties with non-null values will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be updated. If FALSE, only non-null values will be updated.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the update query.

26. updateQuery

Declaration

public function updateQuery(
    bool $includeNull = false
) : PicoDatabaseQueryBuilder
{
}

Description

Get the query for updating data.

This method prepares a query to update data in the database. It can be used to manually execute the query. If $includeNull is TRUE, properties with null values will be included in the update query. If FALSE, only non-null properties will be updated.

Parameters

$includeNull

If TRUE, all properties, including null, will be included in the update query. If FALSE, only non-null properties will be included.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the update query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

27. delete

Declaration

public function delete() : PDOStatement
{
}

Description

Delete data from the database.

This method deletes data associated with the current object from the database.

Return

PDOStatement

Returns a PDOStatement object for further database interaction.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error executing the delete query.

28. deleteQuery

Declaration

public function deleteQuery() : PicoDatabaseQueryBuilder
{
}

Description

Get the query for deleting data.

This method prepares a query to delete data from the database. It can be used to manually execute the query.

Return

PicoDatabaseQueryBuilder

Returns a PicoDatabaseQueryBuilder object for building the delete query.

Throws

NoDatabaseConnectionException

If there is no active database connection.

29. startTransaction

Declaration

public function startTransaction() : self
{
}

Description

Starts a database transaction.

This method begins a new database transaction. It delegates the actual transaction initiation to the transactionalCommand method, passing the "start" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error while starting the transaction.

30. commit

Declaration

public function commit() : self
{
}

Description

Commits the current database transaction.

This method commits the current transaction. If successful, it makes all database changes made during the transaction permanent. It delegates to the transactionalCommand method with the "commit" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the commit process.

31. rollback

Declaration

public function rollback() : self
{
}

Description

Rolls back the current database transaction.

This method rolls back the current transaction, undoing all database changes made during the transaction. It calls the transactionalCommand method with the "rollback" command.

Return

self

The current instance of the class for method chaining.

Throws

NoDatabaseConnectionException

If there is no active database connection.

PDOException

If there is an error during the rollback process.

32. where

Declaration

public function where(
    PicoSpecification $specification
) : PicoDatabasePersistenceExtended
{
}

Description

Get a MagicObject with a WHERE specification.

This method applies a WHERE condition to the database query using the provided specification. The specification is an instance of PicoSpecification which defines the filtering criteria.

Parameters

$specification

The specification to define the WHERE condition.

Return

PicoDatabasePersistenceExtended

Returns an instance of PicoDatabasePersistenceExtended

Throws

NoDatabaseConnectionException

If there is no active database connection.

33. modifyNullProperties

Declaration

private function modifyNullProperties(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Modify properties with null values.

This method tracks properties that are assigned a null value, storing them in a _nullProperties array. If a property is set to null, it is added to the _nullProperties array; if it's set to a non-null value, it is removed from the array.

Parameters

$propertyName

The name of the property to check and modify.

$propertyValue

The value to be assigned to the property.

Return

self

Returns the current instance for method chaining.

34. set

Declaration

public function set(
    string $propertyName,
    mixed|null $propertyValue,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Set property value.

Parameters

$propertyName

Property name

$propertyValue

Property value

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

35. push

Declaration

public function push(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

36. append

Declaration

public function append(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the end of an array property (alias for push).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

37. unshift

Declaration

public function unshift(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property.

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

38. prepend

Declaration

public function prepend(
    string $propertyName,
    mixed $propertyValue
) : self
{
}

Description

Adds an element to the beginning of an array property (alias for unshift).

Parameters

$propertyName

Property name

$propertyValue

Property value

Return

self

Returns the current instance for method chaining.

39. pop

Declaration

public function pop(
    string $propertyName
) : mixed
{
}

Description

Remove and return the last element of an array property.

This method removes the last element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the last element will be removed.

Return

mixed

The last element of the array, or null if the property is not an array or doesn't exist.

40. shift

Declaration

public function shift(
    string $propertyName
) : mixed
{
}

Description

Remove and return the first element of an array property.

This method removes the first element from an array property and returns it. If the specified property is not an array or does not exist, null is returned.

Parameters

$propertyName

The name of the property (array) from which the first element will be removed.

Return

mixed

The first element of the array, or null if the property is not an array or doesn't exist.

41. get

Declaration

public function get(
    string $propertyName
) : mixed|null
{
}

Description

Get the value of a property.

This method retrieves the value of the specified property. If the property does not exist, it returns null.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property, or null if the property is not set.

42. getOrDefault

Declaration

public function getOrDefault(
    string $propertyName,
    mixed|null $defaultValue = null
) : mixed|null
{
}

Description

Get the value of a property or a default value if the property is not set.

This method retrieves the value of the specified property. If the property is not set, the provided default value is returned.

Parameters

$propertyName

The name of the property to retrieve.

$defaultValue

The default value to return if the property is not set.

Return

mixed|null

The value of the property, or the default value if the property is not set.

43. __set

Declaration

public function __set(
    string $propertyName,
    mixed $propertyValue
)
{
}

Description

Set property value (magic setter).

Parameters

$propertyName

Property name

$propertyValue

Property value

44. __get

Declaration

public function __get(
    string $propertyName
) : mixed|null
{
}

Description

Magic method to get the value of a property.

This method is automatically called when an undefined or inaccessible property is accessed. It checks if the property has been set (including null values) using the __isset method and retrieves its value via the get method if it exists.

Parameters

$propertyName

The name of the property to retrieve.

Return

mixed|null

The value of the property if it is set, or null if the property is not set or accessible.

45. __isset

Declaration

public function __isset(
    string $propertyName
) : bool
{
}

Description

Magic method to check if a property is set (including null).

This method is automatically called when checking if an undefined or inaccessible property is set using isset(). It checks if the property exists and is set (even if its value is null).

Parameters

$propertyName

The name of the property to check.

Return

bool

True if the property is set (including null), false otherwise.

46. __unset

Declaration

public function __unset(
    string $propertyName
) : void
{
}

Description

Magic method to unset a property.

This method is automatically called when a property is unset using unset(). It unsets the specified property from the object.

Parameters

$propertyName

The name of the property to unset.

Return

void
47. copyValueFrom

Declaration

public function copyValueFrom(
    self|mixed $source,
    array|null $filter = null,
    bool $includeNull = false
) : self
{
}

Description

Copy values from another object to the current instance.

This method copies property values from the provided source object to the current instance. Optionally, a filter can be applied to specify which properties to copy, and whether null values should be included.

Parameters

$source

The source object or data from which values will be copied. If a non-object is provided, this may result in unexpected behavior.

$filter

An optional array of property names to filter which properties are copied. If null, all properties are copied.

$includeNull

Flag indicating whether to include properties with null values. If false, properties with null values will be excluded from the copy.

Return

self

Returns the current instance for method chaining after copying the values.

48. removeValue

Declaration

private function removeValue(
    string $propertyName,
    bool $skipModifyNullProperties = false
) : self
{
}

Description

Remove property value and set it to null.

Parameters

$propertyName

Property name

$skipModifyNullProperties

Skip modifying null properties

Return

self

Returns the current instance for method chaining.

49. tableInfo

Declaration

public function tableInfo() : PicoTableInfo
{
}

Description

Retrieve table information for the current instance.

This method retrieves the table information (e.g., schema, columns) associated with the current object. It lazily loads the table information, meaning it will be fetched only once and cached for future calls to improve performance.

Return

PicoTableInfo

Returns an instance of the PicoTableInfo class containing the table schema and other related metadata.

50. defaultValue

Declaration

public function defaultValue(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get default values for properties

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing default values

51. value

Declaration

public function value(
    bool $snakeCase = false
) : stdClass
{
}

Description

Get the object values

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

stdClass

An object containing the values of the properties

52. valueObject

Declaration

public function valueObject(
    boolean|null $snakeCase = null
) : stdClass
{
}

Description

Get the object value as a specified format

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case; if null, default behavior is used

Return

stdClass

An object representing the value of the instance

53. valueArray

Declaration

public function valueArray(
    bool $snakeCase = false
) : array
{
}

Description

Get the object value as an associative array

Parameters

$snakeCase

Flag indicating whether to convert property names to snake case

Return

array

An associative array representing the object values

54. valueArrayUpperCamel

Declaration

public function valueArrayUpperCamel() : array
{
}

Description

Get the object value as an associative array with the first letter of each key in upper camel case

Return

array

An associative array with keys in upper camel case

55. _snakeJson

Declaration

protected function _snakeJson() : bool
{
}

Description

Check if the JSON naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

56. _snakeYaml

Declaration

protected function _snakeYaml() : bool
{
}

Description

Check if the YAML naming strategy is snake case

Return

bool

True if the naming strategy is snake case; otherwise, false

57. _upperCamel

Declaration

protected function _upperCamel() : bool
{
}

Description

Check if the JSON naming strategy is upper camel case

Return

bool

True if the naming strategy is upper camel case; otherwise, false

58. _camel

Declaration

protected function _camel() : bool
{
}

Description

Check if the JSON naming strategy is camel case

Return

bool

True if the naming strategy is camel case; otherwise, false

59. _pretty

Declaration

protected function _pretty() : bool
{
}

Description

Check if the JSON output should be prettified

Return

bool

True if JSON output is set to be prettified; otherwise, false

60. _isArray

Declaration

private function _isArray(
    mixed $params
) : bool
{
}

Description

Checks if the provided parameter is an array.

This function verifies if the given parameter is set and is of type array. It is a helper method used to validate the type of data before performing any operations on it that require an array.

Parameters

$params

The parameter to check.

Return

bool

Returns true if the parameter is set and is an array, otherwise returns false.

61. _isNotNullAndNotEmpty

Declaration

private function _isNotNullAndNotEmpty(
    mixed $value
) : bool
{
}

Description

Check if a value is not null and not empty

Parameters

$value

The value to check

Return

bool

True if the value is not null and not empty; otherwise, false

62. propertyList

Declaration

protected function propertyList(
    bool $reflectSelf = false,
    bool $asArrayProps = false
) : array
{
}

Description

Get a list of properties

Parameters

$reflectSelf

Flag indicating whether to reflect properties of the current class

$asArrayProps

Flag indicating whether to return properties as an array

Return

array

An array of property names or ReflectionProperty objects

63. listAll

Declaration

public function listAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null
) : PicoPageData
{
}

Description

List all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

64. countData

Declaration

private function countData(
    PicoDatabasePersistence $persist,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable,
    PicoSortable|string|null $sortable,
    int $findOption = 0,
    array|null $result = null
) : int
{
}

Description

Count the data based on specifications

Parameters

$persist

The persistence object

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$findOption

The find option

$result

The result set

Return

int

The count of matching records

65. findOne

Declaration

public function findOne(
    PicoSpecification|null $specification = null,
    PicoSortable|string|null $sortable = null,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record based on specifications

Parameters

$specification

The specification for filtering

$sortable

The sorting criteria

$subqueryMap

An optional map of subqueries

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

66. findAll

Declaration

public function findAll(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

67. findAllAsc

Declaration

public function findAllAsc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in ascending order

Return

PicoPageData

The paginated data

68. findAllDesc

Declaration

public function findAllDesc() : PicoPageData
{
}

Description

Find all records without filters, sorted by primary key in descending order

Return

PicoPageData

The paginated data

69. findSpecific

Declaration

public function findSpecific(
    string $selected,
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap = null,
    int $findOption = 0
) : PicoPageData
{
}

Description

Find specific records

Parameters

$selected

The selected field(s)

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

70. countAll

Declaration

public function countAll(
    PicoSpecification|null $specification = null,
    PicoPageable|null $pageable = null,
    PicoSortable|null $sortable = null
) : int|false
{
}

Description

Count all records based on specifications

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

int|false

The count of records or false on error

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

71. findAllQuery

Declaration

public function findAllQuery(
    PicoSpecification|null $specification = null,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null
) : PicoDatabaseQueryBuilder
{
}

Description

Build a query to find all records

Parameters

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

Return

PicoDatabaseQueryBuilder

The query builder

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

72. find

Declaration

public function find(
    mixed $params
) : self
{
}

Description

Find one record by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance.

Throws

NoRecordFoundException

if no record is found

NoDatabaseConnectionException

if no database connection is established

73. findIfExists

Declaration

public function findIfExists(
    array $params
) : self
{
}

Description

Find one record if it exists by primary key value

Parameters

$params

The parameters for the search

Return

self

The found instance. or the current instance if not found

74. findBy

Declaration

private function findBy(
    string $method,
    mixed $params,
    PicoSpecification|null $specification,
    PicoPageable|string|null $pageable = null,
    PicoSortable|string|null $sortable = null,
    bool $passive = false,
    array|null $subqueryMap,
    int $findOption
) : PicoPageData
{
}

Description

Find records by specified parameters

Parameters

$method

The method to find by

$params

The parameters for the search

$specification

The specification for filtering

$pageable

The pagination information

$sortable

The sorting criteria

$passive

Flag indicating whether the object is passive

$subqueryMap

An optional map of subqueries

$findOption

The find option

Return

PicoPageData

The paginated data

Throws

NoRecordFoundException

if no records are found

NoDatabaseConnectionException

if no database connection is established

75. countBy

Declaration

private function countBy(
    string $method,
    mixed $params
) : int
{
}

Description

Count data from the database.

Parameters

$method

The method used for finding.

$params

The parameters to use for the count.

Return

int

The count of matching records.

Throws

NoDatabaseConnectionException

If there is no database connection.

76. deleteBy

Declaration

private function deleteBy(
    string $method,
    mixed $params
) : int
{
}

Description

Delete records based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

int

The number of deleted records.

Throws

NoDatabaseConnectionException

If there is no database connection.

77. findOneWithPrimaryKeyValue

Declaration

public function findOneWithPrimaryKeyValue(
    mixed $primaryKeyVal,
    array|null $subqueryMap = null
) : self
{
}

Description

Find one record using the primary key value.

Parameters

$primaryKeyVal

The primary key value.

$subqueryMap

Optional subquery map for additional queries.

Return

self

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

78. findOneBy

Declaration

private function findOneBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance.

Throws

NoRecordFoundException

If no record is found.

NoDatabaseConnectionException

If there is no database connection.

79. findOneIfExistsBy

Declaration

private function findOneIfExistsBy(
    string $method,
    mixed $params,
    PicoSortable|string|null $sortable = null
) : object
{
}

Description

Find one record if it exists based on parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

$sortable

Optional sorting criteria.

Return

object

The found instance or the current instance if not found.

Throws

NoDatabaseConnectionException

If there is no database connection.

80. deleteOneBy

Declaration

private function deleteOneBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Delete one record based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the deletion.

Return

bool

True on success; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

81. existsBy

Declaration

private function existsBy(
    string $method,
    mixed $params
) : bool
{
}

Description

Check if a record exists based on specified parameters.

Parameters

$method

The method used for finding.

$params

The parameters to use for the search.

Return

bool

True if the record exists; otherwise, false.

Throws

NoDatabaseConnectionException

If there is no database connection.

82. booleanToTextBy

Declaration

private function booleanToTextBy(
    string $propertyName,
    string[] $params
) : string
{
}

Description

Convert a boolean value to text based on the specified property name.

Parameters

$propertyName

The property name to check.

$params

The text representations for true and false.

Return

string

The corresponding text representation.

83. toArrayObject

Declaration

private function toArrayObject(
    array $result,
    bool $passive = false
) : array
{
}

Description

Convert the result to an array of objects.

Parameters

$result

The result set to convert.

$passive

Flag indicating whether the objects are passive.

Return

array

An array of objects.

84. size

Declaration

public function size() : int
{
}

Description

Get the number of properties of the object.

Return

int

The number of properties.

85. __call

Declaration

public function __call(
    string $method,
    mixed $params
) : mixed|null
{
}

Description

Magic method called when a user calls any undefined method. The __call method checks the prefix of the called method and invokes the appropriate method according to its name and parameters.

Method Descriptions:

  • hasValue: Checks if the property has a value.

    • Example: $object->hasValuePropertyName();
  • isset: Checks if the property is set.

    • Example: $object->issetPropertyName();
  • is: Retrieves the property value as a boolean.

    • Example: $isActive = $object->isActive();
  • equals: Checks if the property value equals the given value.

    • Example: $isEqual = $object->equalsPropertyName($value);
  • get: Retrieves the property value.

    • Example: $value = $object->getPropertyName();
  • set: Sets the property value.

    • Example: $object->setPropertyName($value);
  • unset: Unsets the property value.

    • Example: $object->unsetPropertyName();
  • push: Adds array elements to a property at the end.

    • Example: $object->pushPropertyName($newElement);
  • append: Appends array elements to a property at the end.

    • Example: $object->appendPropertyName($newElement);
  • unshift: Adds array elements to a property at the beginning.

    • Example: $object->unshiftPropertyName($newElement);
  • prepend: Prepends array elements to a property at the beginning.

    • Example: $object->prependPropertyName($newElement);
  • pop: Removes the last element from the property.

    • Example: $removedElement = $object->popPropertyName();
  • shift: Removes the first element from the property.

    • Example: $removedElement = $object->shiftPropertyName();
  • findOneBy: Searches for data in the database and returns one record.

    • Example: $record = $object->findOneByPropertyName($value);
    • Requires a database connection.
  • findOneIfExistsBy: Searches for data in the database by any column values and returns one record.

    • Example: $record = $object->findOneIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • deleteOneBy: Deletes data from the database by any column values and returns one record.

    • Example: $deletedRecord = $object->deleteOneByPropertyName($value, $sortable);
    • Requires a database connection.
  • findFirstBy: Searches for data in the database by any column values and returns the first record.

    • Example: $firstRecord = $object->findFirstByColumnName($value);
    • Requires a database connection.
  • findFirstIfExistsBy: Similar to findFirstBy, but returns the first record if it exists.

    • Example: $firstRecord = $object->findFirstIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findLastBy: Searches for data in the database by any column values and returns the last record.

    • Example: $lastRecord = $object->findLastByColumnName($value);
    • Requires a database connection.
  • findLastIfExistsBy: Similar to findLastBy, but returns the last record if it exists.

    • Example: $lastRecord = $object->findLastIfExistsByPropertyName($value, $sortable);
    • Requires a database connection.
  • findBy: Searches for multiple records in the database by any column values.

    • Example: $records = $object->findByColumnName($value);
    • Requires a database connection.
  • countBy: Counts data from the database.

    • Example: $count = $object->countByColumnName();
  • existsBy: Checks for data in the database.

    • Example: $exists = $object->existsByColumn($column);
    • Requires a database connection.
  • deleteBy: Deletes data from the database without reading it first.

    • Example: $object->deleteByPropertyName($value);
    • Requires a database connection.
  • booleanToTextBy: Converts a boolean value to "yes/no" or "true/false" based on given parameters.

    • Example: $result = $object->booleanToTextByActive("Yes", "No");
    • If $obj->active is true, $result will be "Yes"; otherwise, it will be "No".
  • startsWith: Checks if the value starts with a given string.

    • Example: $startsWith = $object->startsWithPropertyName("prefix");
  • endsWith: Checks if the value ends with a given string.

    • Example: $endsWith = $object->endsWithPropertyName("suffix");
  • label: Retrieves the label associated with the given property.

    • If the label is not set, it attempts to fetch it from annotations.
    • Example: $label = $object->labelPropertyName();
  • option: Returns the first parameter if the property is set to true or equals 1; otherwise returns the second parameter.

    • Example: $option = $object->optionPropertyName("Yes", "No");
  • notNull: Checks if the specified property is set (not null).

    • Example: $isNotNull = $object->notNullPropertyName();
  • notEmpty: Checks if the specified property is set and not empty.

    • Example: $isNotEmpty = $object->notEmptyPropertyName();
  • notZero: Checks if the specified property is set and not equal to zero.

    • Example: $isNotZero = $object->notZeroPropertyName();
  • notEquals: Checks if the specified property is set and does not equal the given value.

    • Example: $isNotEqual = $object->notEqualsPropertyName($value);

Parameters

$method

Method name

$params

Parameters for the method

Return

mixed|null

The result of the called method, or null if not applicable

86. __toString

Declaration

public function __toString() : string
{
}

Description

Magic method to convert the object to a string.

Return

string

A JSON representation of the object.

87. stringifyObject

Declaration

private function stringifyObject(
    self $value,
    bool $snake
) : mixed
{
}

Description

Recursively stringify an object or array of objects.

Parameters

$value

The object to stringify.

$snake

Flag to indicate whether to convert property names to snake_case.

Return

mixed

The stringified object or array.

88. dumpYaml

Declaration

public function dumpYaml(
    int|null $inline = null,
    int $indent = 4,
    int $flags = 0
) : string
{
}

Description

Dumps a PHP value to a YAML string.

The dump method, when supplied with an array, converts it into a friendly YAML format.

Parameters

$inline

The level at which to switch to inline YAML. If NULL, the maximum depth will be used.

$indent

The number of spaces to use for indentation of nested nodes.

$flags

A bit field of DUMP_* constants to customize the dumped YAML string.

Return

string

A YAML string representing the original PHP value.

MagicApp\Exceptions\InvalidDownloadException

Declaration

class InvalidDownloadException extends Exception implements Throwable { }

Package

MagicObject\Exceptions

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class InvalidDownloadException

Custom exception for handling errors during download operations. This exception is thrown when there are issues such as network failures, timeouts, or invalid responses during a download process.

Properties

1. previous

Declaration

private Throwable $previous;

Description

Previous exception

Methods

1. __construct

Declaration

public function __construct(
    string $message,
    int $code = 0,
    Throwable|null $previous = null
)
{
}

Description

Constructor for InvalidDownloadException.

Parameters

$message

Exception message

$code

Exception code

$previous

Previous exception

2. getPreviousException

Declaration

public function getPreviousException() : Throwable|null
{
}

Description

Get the previous exception.

Return

Throwable|null

MagicApp\Menu\AccountMenu

Declaration

class AccountMenu extends MagicApp\Menu\BasicMenu { }

Package

MagicApp\Menu

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class AccountMenu

Represents the menu structure for the user account section of the application. The AccountMenu class extends the BasicMenu class and provides functionalities related to rendering and managing a specific set of navigation options for the user account area, such as profile management, account settings, and logout options.

This class can be extended to add additional menu items or behavior specific to the account section, providing a customizable menu system for various user-related actions.

Properties

1. entity

Declaration

protected MagicObject $entity;

Description

Entity

2. specification

Declaration

protected PicoSpecification $specification;

Description

Specification

3. sortable

Declaration

protected PicoSortable $sortable;

Description

Sortable

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $entity,
    PicoSpecification|null $specification = null,
    PicoSortable|null $sortable = null
)
{
}

Description

Constructor

Initializes the BasicMenu with the specified entity, specification, and sortable options.

Parameters

$entity

The entity to be used for data loading.

$specification

Optional. The specification

$sortable

Optional. The sortable options for

2. load

Declaration

public function load() : PicoPageData
{
}

Description

Load data

Loads data from the entity based on the provided specification and sorting options.

Return

PicoPageData

The loaded data.

3. render

Declaration

public function render(
    PicoPageData $data,
    callable $callbackFunction
) : string|null
{
}

Description

Render menu

Renders the menu using the provided callback function on the given data.

Parameters

$data

The data to be rendered.

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output, or null if the callback is not callable.

4. loadAndRender

Declaration

public function loadAndRender(
    callable $callbackFunction
) : string|null
{
}

Description

Load and render menu

Combines loading and rendering the menu in a single method call.

Parameters

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output from the callback function.

MagicApp\Menu\BasicMenu

Declaration

class BasicMenu { }

Package

MagicApp\Menu

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class BasicMenu

Represents a basic menu structure that loads and renders data for the menu using an entity, a specification (for filtering), and sortable options (for ordering). It provides functionality to load data from a database or other entity, apply specifications and sorting, and render the data using a callback function. The BasicMenu class can be extended or customized to cater to various menu structures in an application.

Properties

1. entity

Declaration

protected MagicObject $entity;

Description

Entity

2. specification

Declaration

protected PicoSpecification $specification;

Description

Specification

3. sortable

Declaration

protected PicoSortable $sortable;

Description

Sortable

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $entity,
    PicoSpecification|null $specification = null,
    PicoSortable|null $sortable = null
)
{
}

Description

Constructor

Initializes the BasicMenu with the specified entity, specification, and sortable options.

Parameters

$entity

The entity to be used for data loading.

$specification

Optional. The specification

$sortable

Optional. The sortable options for

2. load

Declaration

public function load() : PicoPageData
{
}

Description

Load data

Loads data from the entity based on the provided specification and sorting options.

Return

PicoPageData

The loaded data.

3. render

Declaration

public function render(
    PicoPageData $data,
    callable $callbackFunction
) : string|null
{
}

Description

Render menu

Renders the menu using the provided callback function on the given data.

Parameters

$data

The data to be rendered.

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output, or null if the callback is not callable.

4. loadAndRender

Declaration

public function loadAndRender(
    callable $callbackFunction
) : string|null
{
}

Description

Load and render menu

Combines loading and rendering the menu in a single method call.

Parameters

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output from the callback function.

MagicApp\Menu\MainMenu

Declaration

class MainMenu extends MagicApp\Menu\BasicMenu { }

Package

MagicApp\Menu

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class MainMenu

Represents the main menu structure that organizes a list of menu items into groups based on specified column names. It extends the BasicMenu class and provides functionality for organizing menu items into logical groups, such as grouping by menu category or other criteria.

This class also supports associating each menu group with a unique identifier and allows for easy retrieval of the grouped menu structure. It is designed to be used in scenarios where menus need to be structured dynamically and grouped based on data stored in an entity or database.

Properties

1. menu

Declaration

private array $menu = array();

Description

Menu structure

2. columnName

Declaration

private string $columnName = '';

Description

Column name for menu group

3. joinColumnName

Declaration

private string $joinColumnName = '';

Description

Join column name for menu group

4. entity

Declaration

protected MagicObject $entity;

Description

Entity

5. specification

Declaration

protected PicoSpecification $specification;

Description

Specification

6. sortable

Declaration

protected PicoSortable $sortable;

Description

Sortable

Methods

1. __construct

Declaration

public function __construct(
    MagicObject[] $menu,
    string $columnName,
    string $joinColumnName
)
{
}

Description

Construct menu

Initializes the MainMenu with a list of menu items, organizing them into groups based on the specified column names.

Parameters

$menu

An array of menu items (MagicObject instances).

$columnName

The column name used to group the menu items.

$joinColumnName

The column name used for joining menu groups.

2. getMenu

Declaration

public function getMenu() : array
{
}

Description

Get menu

Returns the organized menu structure.

Return

array

The organized menu structure grouped by specified column.

3. load

Declaration

public function load() : PicoPageData
{
}

Description

Load data

Loads data from the entity based on the provided specification and sorting options.

Return

PicoPageData

The loaded data.

4. render

Declaration

public function render(
    PicoPageData $data,
    callable $callbackFunction
) : string|null
{
}

Description

Render menu

Renders the menu using the provided callback function on the given data.

Parameters

$data

The data to be rendered.

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output, or null if the callback is not callable.

5. loadAndRender

Declaration

public function loadAndRender(
    callable $callbackFunction
) : string|null
{
}

Description

Load and render menu

Combines loading and rendering the menu in a single method call.

Parameters

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output from the callback function.

MagicApp\Menu\MessageMenu

Declaration

class MessageMenu extends MagicApp\Menu\BasicMenu { }

Package

MagicApp\Menu

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class MessageMenu

Represents a menu for displaying and managing messages within the application. It extends the BasicMenu class and inherits its functionality to load, render, and display menu items. The MessageMenu class can be customized for use cases that specifically require the display of messages, such as user notifications or messaging systems.

Properties

1. entity

Declaration

protected MagicObject $entity;

Description

Entity

2. specification

Declaration

protected PicoSpecification $specification;

Description

Specification

3. sortable

Declaration

protected PicoSortable $sortable;

Description

Sortable

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $entity,
    PicoSpecification|null $specification = null,
    PicoSortable|null $sortable = null
)
{
}

Description

Constructor

Initializes the BasicMenu with the specified entity, specification, and sortable options.

Parameters

$entity

The entity to be used for data loading.

$specification

Optional. The specification

$sortable

Optional. The sortable options for

2. load

Declaration

public function load() : PicoPageData
{
}

Description

Load data

Loads data from the entity based on the provided specification and sorting options.

Return

PicoPageData

The loaded data.

3. render

Declaration

public function render(
    PicoPageData $data,
    callable $callbackFunction
) : string|null
{
}

Description

Render menu

Renders the menu using the provided callback function on the given data.

Parameters

$data

The data to be rendered.

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output, or null if the callback is not callable.

4. loadAndRender

Declaration

public function loadAndRender(
    callable $callbackFunction
) : string|null
{
}

Description

Load and render menu

Combines loading and rendering the menu in a single method call.

Parameters

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output from the callback function.

MagicApp\Menu\MotificationMenu

Declaration

class MotificationMenu extends MagicApp\Menu\BasicMenu { }

Package

MagicApp\Menu

Authors

  1. Kamshory

Links

  1. https://github.com/Planetbiru/MagicApp

Description

Class MotificationMenu

Represents a menu for displaying and managing notifications within the application. It extends the BasicMenu class, which provides the core functionality to load, render, and display menu items. The MotificationMenu class can be used to present notification data, such as system alerts, user notifications, or event-based messages.

Properties

1. entity

Declaration

protected MagicObject $entity;

Description

Entity

2. specification

Declaration

protected PicoSpecification $specification;

Description

Specification

3. sortable

Declaration

protected PicoSortable $sortable;

Description

Sortable

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $entity,
    PicoSpecification|null $specification = null,
    PicoSortable|null $sortable = null
)
{
}

Description

Constructor

Initializes the BasicMenu with the specified entity, specification, and sortable options.

Parameters

$entity

The entity to be used for data loading.

$specification

Optional. The specification

$sortable

Optional. The sortable options for

2. load

Declaration

public function load() : PicoPageData
{
}

Description

Load data

Loads data from the entity based on the provided specification and sorting options.

Return

PicoPageData

The loaded data.

3. render

Declaration

public function render(
    PicoPageData $data,
    callable $callbackFunction
) : string|null
{
}

Description

Render menu

Renders the menu using the provided callback function on the given data.

Parameters

$data

The data to be rendered.

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output, or null if the callback is not callable.

4. loadAndRender

Declaration

public function loadAndRender(
    callable $callbackFunction
) : string|null
{
}

Description

Load and render menu

Combines loading and rendering the menu in a single method call.

Parameters

$callbackFunction

The function to be called for rendering.

Return

string|null

The rendered output from the callback function.

MagicApp\Utility\CloudflareUtil

Declaration

class CloudflareUtil { }

Description

Class CloudflareUtil

A utility class for handling Cloudflare-related operations, specifically for managing IP addresses. This class provides methods to retrieve the client's real IP address when using Cloudflare and to validate IP addresses against known Cloudflare IP ranges.

Properties

1. cloudflareIpRanges

Declaration

public $cloudflareIpRanges = array ( 0 => '204.93.240.0/24', 1 => '204.93.177.0/24', 2 => '199.27.128.0/21', 3 => '173.245.48.0/20', 4 => '103.21.244.0/22', 5 => '103.22.200.0/22', 6 => '103.31.4.0/22', 7 => '141.101.64.0/18', 8 => '108.162.192.0/18', 9 => '190.93.240.0/20', 10 => '188.114.96.0/20', 11 => '197.234.240.0/22', 12 => '198.41.128.0/17', 13 => '162.158.0.0/15', );

Description

@var array IP ranges belonging to Cloudflare.

Methods

1. getClientIp

Declaration

public static function getClientIp(
    bool $validateRequest = false
) : string
{
}

Description

Get the client's real IP address.

This method retrieves the real IP address of the client using the CF-Connecting-IP header provided by Cloudflare. If the header is not present or the request is not validated, it falls back to using the REMOTE_ADDR server variable.

Parameters

$validateRequest

Optional. If true, validates that the

Return

string

The client's IP address.

2. ipInRange

Declaration

public static function ipInRange(
    string $ip,
    string $range
) : bool
{
}

Description

Check if an IP address is within a specified range.

This method determines whether a given IP address falls within a specified IP range, which can be in CIDR format or a custom range.

Parameters

$ip

The IP address to check.

$range

The IP range in CIDR or custom format.

Return

bool

True if the IP is in the range, false otherwise.

3. withRage1

Declaration

public static function withRage1(
    string $ip,
    string $range
) : bool
{
}

Description

Determine if an IP address is within a CIDR range.

Parameters

$ip

The IP address to check.

$range

The CIDR range (e.g., '192.168.1.0/24').

Return

bool

True if the IP is in the CIDR range, false otherwise.

4. withRange2

Declaration

public static function withRange2(
    string $ip,
    string $range
) : bool
{
}

Description

Determine if an IP address is within a non-CIDR range.

Parameters

$ip

The IP address to check.

$range

The range in custom format (e.g., '192.168.1.*' or '192.168.1.0-192.168.1.255').

Return

bool

True if the IP is in the range, false otherwise.

MagicApp\Utility\PeriodUtil

Declaration

class PeriodUtil { }

Description

Class PeriodUtil

Utility class for handling period calculations based on a specific format. This class provides methods to calculate the next and previous periods given a current period in 'YYYYMM' format, allowing for easy date manipulation in applications that require monthly period handling.

Methods

1. nextPeriod

Declaration

public static function nextPeriod(
    string $currentPeriod,
    int $n
) : string
{
}

Description

Get the next period by adding a specified number of months.

This method takes the current period as a string in 'YYYYMM' format and adds a specified number of months to it, returning the resulting period also in 'YYYYMM' format. It handles year rollover when necessary.

Parameters

$currentPeriod

The current period in 'YYYYMM' format.

$n

The number of months to add.

Return

string

The next period in 'YYYYMM' format.

2. previousPeriod

Declaration

public static function previousPeriod(
    string $currentPeriod,
    int $n
) : string
{
}

Description

Get the previous period by subtracting a specified number of months.

This method takes the current period as a string in 'YYYYMM' format and subtracts a specified number of months from it, returning the resulting period also in 'YYYYMM' format. It handles year rollover when subtracting, ensuring valid output.

Parameters

$currentPeriod

The current period in 'YYYYMM' format.

$n

The number of months to subtract.

Return

string

The previous period in 'YYYYMM' format.

MagicApp\Utility\ZipDownloader

Declaration

class ZipDownloader { }

Description

A utility class for creating and downloading ZIP files in PHP.

This class provides methods to compress files or directories into a ZIP archive and offer it as a downloadable file. It includes functionality for:

  • Zipping all files in a directory recursively.
  • Zipping an array of specified file paths.
  • Handling temporary file creation and cleanup.

    Example Use Cases:

  • Provide downloadable backups of folders.
  • Compress selected files into a single archive for sharing.

    Example

    <?php
    try {
     $folderPath = 'path/to';
     ZipDownloader::downloadFolderAsZip($folderPath, 'my-files.zip');
    } catch (Exception $e) {
     echo "Error: " . $e->getMessage();
    }

    or

    <?php
    try {
     $files = [
         'path/to/file1.txt',
         'path/to/file2.jpg',
         'path/to/file3.pdf'
     ];
     ZipDownloader::downloadFilesAsZip($files, 'my-files.zip');
    } catch (Exception $e) {
     echo "Error: " . $e->getMessage();
    }

    Features:

  • Automatically handles folder structures in ZIP files.
  • Validates file paths and directories before processing.
  • Integrates seamless ZIP file download via HTTP headers.

Constants

const ZIP_FILE_CREATION_FAILED = 'Failed to create ZIP file: ';
const FILE_NOT_FOUND = 'The file was not found: ';
const FOLDER_NOT_FOUND = 'The folder was not found: ';

Methods

1. downloadFolderAsZip

Declaration

public static function downloadFolderAsZip(
    string $folderPath,
    string $zipFileName
)
{
}

Description

Create a ZIP file from a folder and download it.

Parameters

$folderPath

Path to the folder containing files to include in the ZIP.

$zipFileName

Name of the ZIP file to create.

Throws

InvalidDownloadException

If the folder doesn't exist or can't create the ZIP file.

2. downloadFilesAsZip

Declaration

public static function downloadFilesAsZip(
    string[] $filePaths,
    string $zipFileName
)
{
}

Description

Create a ZIP file from an array of file paths and download it.

Parameters

$filePaths

Array of file paths to include in the ZIP.

$zipFileName

Name of the ZIP file to create.

Throws

InvalidDownloadException

If a file path is invalid or the ZIP cannot be created.

3. downloadFilesAsNamedZip

Declaration

public static function downloadFilesAsNamedZip(
    array $filePaths,
    string $zipFileName
)
{
}

Description

Create a ZIP file from an associated array of file paths and download it.

Parameters

$filePaths

Associative array of file paths and their human-readable names.

$zipFileName

Name of the ZIP file to create.

Throws

InvalidDownloadException

If a file path is invalid or the ZIP cannot be created.

4. addFolderToZip

Declaration

private static function addFolderToZip(
    string $folderPath,
    ZipArchive $zip,
    string $basePath = ''
)
{
}

Description

Recursively add files and folders to a ZIP archive.

Parameters

$folderPath

Path to the folder.

$zip

ZipArchive object.

$basePath

Base path for relative paths in the ZIP.

5. downloadZipFile

Declaration

private static function downloadZipFile(
    string $zipFilePath,
    string $zipFileName
)
{
}

Description

Send the generated ZIP file to the client for download and clean up.

Parameters

$zipFilePath

Path to the ZIP file on the server.

$zipFileName

Name of the ZIP file for the download.

MagicApp\XLSX\CSVDocumentWriter

Declaration

class CSVDocumentWriter extends MagicApp\XLSX\DocumentWriter { }

Description

Class CSVDocumentWriter

Responsible for generating CSV documents from provided page data. This class extends DocumentWriter and implements methods to write data in CSV format, including handling headers and utilizing custom writer functions for formatted data output.

Properties

3. headerFormat

Declaration

protected array $headerFormat = array();

Description

Header format

4. appLanguage

Declaration

protected AppLanguage $appLanguage;

Description

Application language

Methods

1. write

Declaration

public function write(
    PicoPageData $pageData,
    string $fileName,
    string $sheetName,
    string[] $headerFormat,
    callable $writerFunction,
    boolean $useTemporary = true
) : self
{
}

Description

Write data to a CSV file and prepare for download

Parameters

$pageData

Page data

$fileName

File name for the download

$sheetName

Sheet name (not used in CSV)

$headerFormat

Data format for headers

$writerFunction

Function to write formatted data

$useTemporary

Flag to use temporary file

Return

self

The current instance, allowing method chaining

2. writeDataWithoutFormat

Declaration

private function writeDataWithoutFormat(
    PicoPageData $pageData
) : void
{
}

Description

Write data without specific format

Parameters

$pageData

Page data

Return

void
3. writeHeader

Declaration

private function writeHeader(
    string[] $keys
) : self
{
}

Description

Write header format to the CSV

Parameters

$keys

Data keys

Return

self

The current instance, allowing method chaining

4. writeData

Declaration

private function writeData(
    string[] $keys,
    MagicObject $row
) : self
{
}

Description

Write a single row of data to the CSV

Parameters

$keys

Data keys

$row

Data row

Return

self

The current instance, allowing method chaining

5. writeDataWithFormat

Declaration

private function writeDataWithFormat(
    PicoPageData $pageData,
    string[] $headerFormat,
    callable $writerFunction
) : void
{
}

Description

Write data using the provided format

Parameters

$pageData

Page data

$headerFormat

Data format

$writerFunction

Writer function for formatted data

Return

void
6. writeRow

Declaration

private function writeRow(
    array $data
) : self
{
}

Description

Write a line of data to the CSV

Parameters

$data

Array of values to write

Return

self

The current instance, allowing method chaining

7. fputcsv

Declaration

private function fputcsv(
    resource $handle,
    mixed[] $fields,
    string $delimiter = ',',
    string $enclosure = '"',
    string $escape_char = '\\',
    string $record_separator = ' '
) : self
{
}

Description

Custom implementation of fputcsv

Parameters

$handle

File handle

$fields

Array of values to write

$delimiter

Field delimiter

$enclosure

Field enclosures

$escape_char

Escape enclosure characters in fields

$record_separator

Record separator

Return

self

The current instance, allowing method chaining

8. __construct

Declaration

public function __construct(
    AppLanguage $appLanguage
)
{
}

Description

Constructor

Parameters

$appLanguage

Application language instance

9. noFetchData

Declaration

protected function noFetchData(
    PicoPageData $pageData
) : bool
{
}

Description

Check if no data has been fetched

Parameters

$pageData

Page data

Return

bool

True if no data has been fetched, false otherwise

10. getAppLanguage

Declaration

public function getAppLanguage() : AppLanguage
{
}

Description

Get the application language

Return

AppLanguage

The current application language

11. setAppLanguage

Declaration

public function setAppLanguage(
    AppLanguage $appLanguage
) : DocumentWriter
{
}

Description

Set the application language

Parameters

$appLanguage

Application language

Return

DocumentWriter
12. getXLSXDocumentWriter

Declaration

public static function getXLSXDocumentWriter(
    AppLanguage $appLanguage
) : XLSXDocumentWriter
{
}

Description

Create an instance of XLSXDocumentWriter

Parameters

$appLanguage

Application language

Return

XLSXDocumentWriter

An instance of XLSXDocumentWriter

13. getCSVDocumentWriter

Declaration

public static function getCSVDocumentWriter(
    AppLanguage $appLanguage
) : CSVDocumentWriter
{
}

Description

Create an instance of CSVDocumentWriter

Parameters

$appLanguage

Application language

Return

CSVDocumentWriter

An instance of CSVDocumentWriter

MagicApp\XLSX\DocumentWriter

Declaration

class DocumentWriter { }

Description

Class DocumentWriter

Abstract class for writing documents in different formats (e.g., XLSX, CSV). It provides methods for setting and retrieving application language and for checking data fetching options. Specific document writing logic should be implemented in subclasses such as XLSXDocumentWriter and CSVDocumentWriter.

Properties

1. headerFormat

Declaration

protected array $headerFormat = array();

Description

Header format

2. appLanguage

Declaration

protected AppLanguage $appLanguage;

Description

Application language

Methods

1. __construct

Declaration

public function __construct(
    AppLanguage $appLanguage
)
{
}

Description

Constructor

Parameters

$appLanguage

Application language instance

2. noFetchData

Declaration

protected function noFetchData(
    PicoPageData $pageData
) : bool
{
}

Description

Check if no data has been fetched

Parameters

$pageData

Page data

Return

bool

True if no data has been fetched, false otherwise

3. getAppLanguage

Declaration

public function getAppLanguage() : AppLanguage
{
}

Description

Get the application language

Return

AppLanguage

The current application language

4. setAppLanguage

Declaration

public function setAppLanguage(
    AppLanguage $appLanguage
) : DocumentWriter
{
}

Description

Set the application language

Parameters

$appLanguage

Application language

Return

DocumentWriter
5. getXLSXDocumentWriter

Declaration

public static function getXLSXDocumentWriter(
    AppLanguage $appLanguage
) : XLSXDocumentWriter
{
}

Description

Create an instance of XLSXDocumentWriter

Parameters

$appLanguage

Application language

Return

XLSXDocumentWriter

An instance of XLSXDocumentWriter

6. getCSVDocumentWriter

Declaration

public static function getCSVDocumentWriter(
    AppLanguage $appLanguage
) : CSVDocumentWriter
{
}

Description

Create an instance of CSVDocumentWriter

Parameters

$appLanguage

Application language

Return

CSVDocumentWriter

An instance of CSVDocumentWriter

MagicApp\XLSX\IOException

Declaration

class IOException extends Exception implements Throwable { }

Description

Class IOException

Custom exception class for handling input/output errors.

Properties

1. previous

Declaration

private Throwable $previous;

Description

Previous exception that led to this exception

Methods

1. __construct

Declaration

public function __construct(
    string $message,
    int $code = 0,
    Throwable|null $previous = null
)
{
}

Description

IOException constructor.

Parameters

$message

Exception message

$code

Exception code

$previous

Previous exception

2. getPreviousException

Declaration

public function getPreviousException() : Throwable|null
{
}

Description

Get the previous exception

Return

Throwable|null

MagicApp\XLSX\XLSXBuffererWriter

Declaration

class XLSXBuffererWriter { }

Description

Class XLSXBuffererWriter

This class is responsible for writing data to an XLSX file in a buffered manner. It manages a write buffer to optimize file operations, flushing data to the underlying file resource when the buffer reaches a certain size. The class also includes functionality to validate UTF-8 encoding for the data being written.

Properties

1. fd

Declaration

protected resource $fd;

Description

Resource to file

2. buffer

Declaration

protected string $buffer = '';

Description

Buffer

3. checkUtf8

Declaration

protected boolean $checkUtf8 = false;

Description

Flag to check UTF-8 encoding

Methods

1. __construct

Declaration

public function __construct(
    string $filename,
    string $fd_fopen_flags = 'w',
    boolean $checkUtf8 = false
)
{
}

Description

Constructor

Parameters

$filename

File name

$fd_fopen_flags

Open file flag

$checkUtf8

Flag to check UTF-8 encoding

2. write

Declaration

public function write(
    string $string
) : self
{
}

Description

Write to buffer

Parameters

$string

Data to write

Return

self

The current instance, allowing method chaining

3. purge

Declaration

protected function purge() : self
{
}

Description

Purge the buffer, writing its contents to the file

Return

self

The current instance, allowing method chaining

4. close

Declaration

public function close() : self
{
}

Description

Close the file and flush any remaining buffer

Return

self

The current instance, allowing method chaining

5. __destruct

Declaration

public function __destruct()
{
}

Description

Destructor

Automatically closes the file when the object is destroyed

6. ftell

Declaration

public function ftell() : integer
{
}

Description

Returns the current position of the file read/write pointer

Return

integer

Current file position or -1 on error

7. fseek

Declaration

public function fseek(
    integer $pos
) : integer
{
}

Description

Seeks on a file pointer

Parameters

$pos

Position to seek to

Return

integer

0 on success, -1 on failure

8. isValidUTF8

Declaration

protected static function isValidUTF8(
    string $string
) : boolean
{
}

Description

Validate UTF-8 encoding of a string

Parameters

$string

String to validate

Return

boolean

True if valid UTF-8, false otherwise

MagicApp\XLSX\XLSXDataFormat

Declaration

class XLSXDataFormat { }

Description

Class XLSXDataFormat

This class is responsible for defining the data format for columns in an XLSX file based on a given entity. It maps the entity's properties to Excel-compatible data types, allowing for precision settings for numeric values. It dynamically generates getter methods for accessing formatted data types based on the entity's schema.

Properties

1. columns

Declaration

private array $columns = array();

Description

Columns

2. precision

Declaration

private integer $precision;

Description

Precision

Methods

1. __construct

Declaration

public function __construct(
    MagicObject $entity,
    integer|null $precision = null
)
{
}

Description

Constructor

Parameters

$entity

The entity to map

$precision

The precision for numeric values

2. __call

Declaration

public function __call(
    string $name,
    array $arguments
) : mixed|null|void
{
}

Description

Magic method for dynamic getter methods

Parameters

$name

Method name

$arguments

Method arguments

Return

mixed|null|void
3. toExcelType

Declaration

public function toExcelType(
    string $type
) : XLSXDataType
{
}

Description

Convert to Excel type

Parameters

$type

The type to convert

Return

XLSXDataType

MagicApp\XLSX\XLSXDataType

Declaration

class XLSXDataType { }

Description

Class XLSXDataType

This class defines various data types that can be used in an XLSX file. It maps database column types to Excel data types, handling conversions and precision for numeric values. The class provides methods for determining the appropriate Excel format based on the column type and allows for customized number formatting.

Constants

const TYPE_DOUBLE = 'double';
const TYPE_INTEGER = 'integer';
const TYPE_STRING = 'string';
const TYPE_DATETIME = 'datetime';
const TYPE_DATE = 'date';
const TYPE_TIME = 'time';

Properties

1. columnType

Declaration

private string $columnType;

Description

Column type

2. map

Declaration

private string[] $map = array ( 'double' => 'double', 'float' => 'double', 'numeric' => 'double', 'real' => 'double', 'bigint' => 'integer', 'smallint' => 'integer', 'tinyint(1)' => 'string', 'tinyint' => 'integer', 'integer' => 'integer', 'int' => 'integer', 'serial' => 'integer', 'bigserial' => 'integer', 'varchar' => 'string', 'character varying' => 'string', 'char' => 'string', 'character' => 'string', 'tinytext' => 'string', 'mediumtext' => 'string', 'longtext' => 'string', 'text' => 'string', 'string' => 'string', 'enum' => 'string', 'blob' => 'string', 'bool' => 'string', 'boolean' => 'string', 'timestamp' => 'datetime', 'timestamp without time zone' => 'datetime', 'timestamp with time zone' => 'datetime', 'datetime' => 'datetime', 'date' => 'date', 'time' => 'time', 'time without time zone' => 'time', 'time with time zone' => 'time', );

Description

Type map for MySQL, PostgreSQL, and SQLite

3. precision

Declaration

private integer $precision;

Description

Precision

Methods

1. __construct

Declaration

public function __construct(
    string $columnType,
    integer|null $precision = null
)
{
}

Description

Constructor

Parameters

$columnType

Column type

$precision

Precision

2. convertToExcel

Declaration

public function convertToExcel() : string
{
}

Description

Convert to Excel type

Return

string
3. getNumberFormat

Declaration

public function getNumberFormat(
    mixed $precision
) : string
{
}

Description

Get number format based on precision

Parameters

$precision

Precision

Return

string
4. toString

Declaration

public function toString() : string
{
}

Description

Convert to string representation

Return

string
5. __toString

Declaration

public function __toString() : string
{
}

Description

Convert to string representation

Return

string

MagicApp\XLSX\XLSXDocumentWriter

Declaration

class XLSXDocumentWriter extends MagicApp\XLSX\DocumentWriter { }

Description

Class XLSXDocumentWriter

This class is responsible for writing data to an XLSX document. It handles both formatted and unformatted data and manages the creation of the sheet headers and rows based on the provided data.

Properties

1. headerFormat

Declaration

protected array $headerFormat = array();

Description

Header format

2. appLanguage

Declaration

protected AppLanguage $appLanguage;

Description

Application language

Methods

1. write

Declaration

public function write(
    PicoPageData $pageData,
    string $fileName,
    string $sheetName,
    array $headerFormat,
    callable $writerFunction,
    bool $useTemporary = true
) : self
{
}

Description

Write data to an XLSX file

Parameters

$pageData

Page data to write

$fileName

File name for the output

$sheetName

Name of the sheet to create

$headerFormat

Data format for the header

$writerFunction

Function to format data

$useTemporary

Whether to use a temporary file

Return

self

The current instance, allowing method chaining

2. writeDataWithoutFormat

Declaration

private function writeDataWithoutFormat(
    XLSXWriter $writer,
    PicoPageData $pageData,
    string $sheetName
) : XLSXWriter
{
}

Description

Write data without specific formatting

Parameters

$writer

XLSX writer instance

$pageData

Page data to write

$sheetName

Name of the sheet

Return

XLSXWriter
3. writeHeader

Declaration

private function writeHeader(
    XLSXWriter $writer,
    string $sheetName,
    array $keys
) : XLSXWriter
{
}

Description

Write the header row to the XLSX sheet

Parameters

$writer

XLSX writer instance

$sheetName

Name of the sheet

$keys

Data keys for the header

Return

XLSXWriter
4. writeData

Declaration

private function writeData(
    XLSXWriter $writer,
    string $sheetName,
    array $keys,
    MagicObject $row
) : XLSXWriter
{
}

Description

Write a data row to the XLSX sheet

Parameters

$writer

XLSX writer instance

$sheetName

Name of the sheet

$keys

Data keys

$row

Data row to write

Return

XLSXWriter
5. writeDataWithFormat

Declaration

private function writeDataWithFormat(
    XLSXWriter $writer,
    PicoPageData $pageData,
    string $sheetName,
    array $headerFormat,
    callable $writerFunction
) : XLSXWriter
{
}

Description

Write data with specific formatting

Parameters

$writer

XLSX writer instance

$pageData

Page data to write

$sheetName

Name of the sheet

$headerFormat

Data format for the header

$writerFunction

Function to format data

Return

XLSXWriter
6. __construct

Declaration

public function __construct(
    AppLanguage $appLanguage
)
{
}

Description

Constructor

Parameters

$appLanguage

Application language instance

7. noFetchData

Declaration

protected function noFetchData(
    PicoPageData $pageData
) : bool
{
}

Description

Check if no data has been fetched

Parameters

$pageData

Page data

Return

bool

True if no data has been fetched, false otherwise

8. getAppLanguage

Declaration

public function getAppLanguage() : AppLanguage
{
}

Description

Get the application language

Return

AppLanguage

The current application language

9. setAppLanguage

Declaration

public function setAppLanguage(
    AppLanguage $appLanguage
) : DocumentWriter
{
}

Description

Set the application language

Parameters

$appLanguage

Application language

Return

DocumentWriter
10. getXLSXDocumentWriter

Declaration

public static function getXLSXDocumentWriter(
    AppLanguage $appLanguage
) : XLSXDocumentWriter
{
}

Description

Create an instance of XLSXDocumentWriter

Parameters

$appLanguage

Application language

Return

XLSXDocumentWriter

An instance of XLSXDocumentWriter

11. getCSVDocumentWriter

Declaration

public static function getCSVDocumentWriter(
    AppLanguage $appLanguage
) : CSVDocumentWriter
{
}

Description

Create an instance of CSVDocumentWriter

Parameters

$appLanguage

Application language

Return

CSVDocumentWriter

An instance of CSVDocumentWriter

MagicApp\XLSX\XLSXWriter

Declaration

class XLSXWriter { }

Constants

const EXCEL_2007_MAX_ROW = 1048576;
const EXCEL_2007_MAX_COL = 16384;

Properties

Methods

1. __construct

Declaration

public function __construct()
{
}

Description

Constructor

2. setTitle

Declaration

public function setTitle(
    string $title = ''
) : self
{
}

Description

Set title

Parameters

$title

Return

self

The current instance, allowing method chaining

3. setSubject

Declaration

public function setSubject(
    string $subject = ''
) : self
{
}

Description

Set subject

Parameters

$subject

Return

self

The current instance, allowing method chaining

4. setAuthor

Declaration

public function setAuthor(
    string $author = ''
) : self
{
}

Description

Set author

Parameters

$author

Return

self

The current instance, allowing method chaining

5. setCompany

Declaration

public function setCompany(
    string $company = ''
) : self
{
}

Description

Set company

Parameters

$company

Return

self

The current instance, allowing method chaining

6. setKeywords

Declaration

public function setKeywords(
    string $keywords = ''
) : self
{
}

Description

Set keywords

Parameters

$keywords

Return

self

The current instance, allowing method chaining

7. setDescription

Declaration

public function setDescription(
    string $description = ''
) : self
{
}

Description

Set description

Parameters

$description

Return

self

The current instance, allowing method chaining

8. setTempDir

Declaration

public function setTempDir(
    string $tempdir = ''
) : self
{
}

Description

Set temporary directory

Parameters

$tempdir

Return

self

The current instance, allowing method chaining

9. setRightToLeft

Declaration

public function setRightToLeft(
    boolean $isRightToLeft = false
) : self
{
}

Description

Set right to left

Parameters

$isRightToLeft

Return

self

The current instance, allowing method chaining

10. __destruct

Declaration

public function __destruct()
{
}

Description

Destructor

11. tempFilename

Declaration

protected function tempFilename() : string
{
}

Description

Get temporary file name

Return

string
12. writeToStdOut

Declaration

public function writeToStdOut() : self
{
}

Description

Read file and write it to sdtout

Return

self

The current instance, allowing method chaining

25. styleFontIndexes

Declaration

protected function styleFontIndexes() : array
{
}

Description

Style font indexes

Return

array
38. array_first_key

Declaration

public static function array_first_key(
    array $arr
) : array|object|int|string|null
{
}

Description

Reset

Parameters

$arr

Return

array|object|int|string|null